Git & Pull Requests
Relevant source files
The following files were used as context for generating this wiki page:
Linux Archductor serves as a control plane for parallel coding agents by utilizing Git worktrees to isolate tasks into distinct workspaces. The system integrates deeply with Git for branch management and the GitHub CLI (gh) for Pull Request (PR) lifecycles, including creation, review tracking, and automated merging.
The workflow revolves around the Workspace unit, which maps 1-to-1 with a Git branch and a physical working tree on disk. This architecture allows developers or agents to run multiple streams of work in parallel without branch switching interference.
Sources: README.md:12-25, progress.md:1-15
Workspace & Branch Architecture
Each workspace is a standalone Git worktree. When a workspace is created, the system initializes a new branch or checks out an existing one, providing an isolated environment for tools like Codex or Claude Code.
Data Relationship Model
The relationship between projects, repositories, and workspaces is hierarchical:
- Project: Represents a single codebase; owns settings and a list of workspaces.
- Repository: The underlying Git codebase.
- Workspace: An isolated copy of the repository for a specific task.
- Branch/Worktree: The physical manifestation of the workspace on disk.
Sources: README.md:12-25, crates/gtk-app/src/main.rs:1072-1085
The diagram shows the 1:1 mapping between workspaces, branches, and worktrees.
Sources: README.md:18-25
Branch Operations
The system provides several GTK-based and CLI controls for managing branches within a workspace:
- Create: Generates a new branch from a base ref.
- Checkout: Switches the active branch in the worktree.
- Rename: Renames the local branch and updates workspace metadata.
- Delete: Safely removes a branch, often paired with workspace deletion.
Sources: crates/gtk-app/src/workspace_command_center.rs:1367-1420, progress.md:18-35
Pull Request Lifecycle
The system automates Pull Request interactions by wrapping gh commands and parsing JSON responses into structured Rust models.
PR States and Readiness
Pull Requests are categorized into specific states to determine available actions in the UI:
| State | Condition | UI Action |
|---|---|---|
| Open | PR exists but checks haven't failed or passed yet. | PR Summary, Reviews, Refresh |
| Pending | GitHub Actions or Deployments are currently running. | PR Summary, Reviews, Refresh |
| Ready | Approved and all checks/deployments passed. | Merge, PR Summary, Refresh |
| Failed | One or more checks or deployments have failed. | Fix checks, PR Summary, Refresh |
| Merged | The PR has been successfully merged upstream. | Continue, Archive |
Sources: crates/gtk-app/src/workspace_command_center.rs:1722-1780, crates/core/src/github_pr.rs:10-85
Automated Readiness Logic
The PullRequestReadiness structure aggregates data from multiple GitHub endpoints to determine if a PR is "Ready to Merge."
Architecture of the readiness check for Pull Requests.
Sources: crates/gtk-app/src/workspace_command_center.rs:1940-1965, crates/core/src/github_pr.rs:87-100
GitHub Integration Data Structures
The core crate defines several structures to handle GitHub's API responses:
PullRequestCheckRun
Represents a single CI/CD status check.
name: The name of the check (e.g., "build").status: The outcome (e.g., "success", "failure", "pending").detail: Optional URL to the logs.
PullRequestReviewThread
Represents a comment thread in a PR.
id: The GitHub GraphQL node ID.resolved: Boolean indicating if the thread is closed.comments: A list ofPullRequestThreadCommentcontaining the author and body.
Sources: crates/core/src/github_pr.rs:4-70
Agent Integration
A key feature of the "Git & Pull Requests" module is the ability to "Stage" PR context for AI agents. This converts complex GitHub states into natural language prompts.
Prompt Generation Types
- Failing Checks: Extracts names and statuses of failed CI runs to instruct the agent to fix them.
- Review Addressal: Consolidates all open review comments into a single task list for the agent.
- Readiness Summary: Provides a high-level rollup of the PR's health, including unresolved threads and deployment statuses.
Sources: crates/core/src/github_pr.rs:380-450, crates/gtk-app/src/workspace_command_center.rs:2100-2150
Code Snippet: Formatting Check Prompts
pub(crate) fn format_pull_request_checks_agent_prompt(
name: &str,
checks: &[PullRequestCheckRun],
) -> String {
let failures = checks.iter().filter(|check| check.is_failure()).collect::<Vec<_>>();
let mut prompt = format!("Fix these failing PR checks for workspace {name}.\n");
if failures.is_empty() {
prompt.push_str("No failing PR checks.\n");
return prompt;
}
// ... logic to list failures ...
prompt
}
Sources: crates/core/src/github_pr.rs:383-398
Merge Blockers
The system supports configurable merge blockers to ensure code quality before a PR is closed. These can be customized in .archductor/settings.toml.
- Open Todos: Blocks merge if the workspace contains unfinished
TODOitems. - Unresolved Comments: Blocks merge if there are local review comments or unresolved GitHub threads.
- Failed Checks: Prevents merging if CI/CD pipelines haven't passed.
- Conflicts: Detects if sibling workspaces have modified the same files.
Sources: crates/gtk-app/src/workspace_command_center.rs:2220-2245, README.md:145-165
Summary
The Git and Pull Request systems in Linux Archductor transform Git worktrees into a robust platform for parallel agent-driven development. By automating the extraction of PR state and converting it into actionable agent prompts, the project streamlines the feedback loop between CI results, human reviews, and automated code corrections. Merging is protected by a multi-layered check system that validates both remote GitHub statuses and local workspace metadata.