GitHub & Linear Integrations

Relevant source files

The following files were used as context for generating this wiki page:

• crates/core/src/linear.rs
• crates/gtk-app/src/projects.rs
• crates/gtk-app/src/workspace_command_center.rs
• progress.md
• README.md

The Linux Archductor project integrates with GitHub and Linear to provide a streamlined workflow for managing coding tasks. These integrations allow users to create isolated workspaces directly from issues or pull requests, automate branch management, and handle pull request (PR) lifecycles within the application environment.

The system relies on external CLI tools and APIs: GitHub interactions are powered by the local gh (GitHub CLI) tool, while Linear interactions communicate directly with Linear's GraphQL API.

Sources: README.md:143-150, progress.md:65-75

Integration Readiness and Preflight

Before initiating workflows, the system performs preflight checks to ensure required authentication and tools are available.

• GitHub: Requires the gh CLI to be installed and the user to be authenticated via gh auth login.
• Linear: Requires a valid LINEAR_API_KEY to be set in the environment.

Sources: crates/gtk-app/src/projects.rs:1145-1155, README.md:150-153

Source Preflight Logic

The application provides a "Check Sources" utility that reports the readiness of both providers.

The diagram shows the branching logic used to validate the environment for external integrations.

Sources: crates/gtk-app/src/projects.rs:563-570, progress.md:65-75

---

Linear Integration Architecture

Linear integration is primarily used for seeding new workspaces with task context. The core logic resides in crates/core/src/linear.rs and utilizes the Linear GraphQL API.

Data Model: LinearIssue

Field	Type	Description
identifier	String	The unique issue ID (e.g., ENG-123).
title	String	The descriptive title of the task.
branch_name	Option<String>	Suggested branch name from Linear.
url	Option<String>	The web URL to the issue.

Sources: crates/core/src/linear.rs:7-12

Linear API Flow

The system executes a GraphQL query using curl. To ensure security, sensitive information (like the API key and query payload) is passed via stdin using curl's --config - flag, preventing the key from appearing in process lists.

The sequence demonstrates the secure communication path between the local application and the Linear API.

Sources: crates/core/src/linear.rs:21-45

---

GitHub Integration Architecture

GitHub integration is more complex, covering both workspace creation and the full PR lifecycle. It interacts with the local environment's gh authentication state.

Workspace Creation from GitHub

Users can create workspaces from existing GitHub Issues or Pull Requests.

1. GitHub Issue: Fetches the issue number, state, and title. It typically creates a new branch named based on the issue title.
2. GitHub PR: Fetches the PR head reference before creating the Git worktree, allowing an agent to work directly on an existing stream of changes.

Sources: crates/gtk-app/src/projects.rs:1044-1065, progress.md:143-150

Pull Request Lifecycle Management

Within a workspace, the "Checks" tab manages the GitHub PR state.

State	Primary Action	Agent Interaction
No PR	Create PR	Queue "Create PR" prompt for Agent
Open	PR Summary / Review	Stage PR context for Agent
Ready	Merge	Archive Workspace (optional)
Failed	Fix Checks	Stage failure details for Agent
Merged	Continue / Archive	Handoff to next task

Sources: crates/gtk-app/src/workspace_command_center.rs:1885-1895, crates/gtk-app/src/workspace_command_center.rs:2050-2065

PR Readiness and Attention

The integration aggregates data from multiple GitHub APIs to provide a "Readiness" summary. This includes:

• Status Rollups: Aggregated GitHub Actions and commit statuses.
• Deployment Rollups: Fetches deployment environments and status URLs.
• Review Threads: Fetches GraphQL Node IDs to allow resolving/reopening threads directly from the CLI/UI.

Sources: progress.md:162-185, crates/gtk-app/src/workspace_command_center.rs:2145-2165

---

Technical Implementation Details

CLI Command Mapping

The system maps UI actions to underlying gh and git commands executed within the workspace context.

// Example logic for loading choices in projects.rs
fn load_github_issue_choices(repo_root: &Path, combo: &ComboBoxText) {
    let output = Command::new("gh")
        .arg("-C")
        .arg(repo_root)
        .args([
            "issue", "list", "--limit", "100", "--state", "open",
            "--json", "number,state,title",
            "--template", "{{range .}}{{.number}}{\"\\t\"}}{{.state}}{\"\\t\"}}{{.title}}{\"\\n\"}}{{end}}",
        ])
        .output();
    // ... parsing and UI population
}

Sources: crates/gtk-app/src/projects.rs:1100-1120

PR Merge Rules

The integration supports custom merge rules defined in .archductor/settings.toml. Merges can be blocked based on:

• Open local todos.
• Open local review comments.
• Failed or pending GitHub PR checks.

Sources: README.md:214-225, progress.md:105-115

Summary

The GitHub and Linear integrations transform Archductor from a simple worktree manager into a task-aware control plane. By pulling context from Linear and managing the lifecycle of GitHub PRs, the system enables coding agents to operate with full awareness of the external project state, while automating the repetitive Git plumbing required to transition between different stages of a task.

Sources: README.md:15-30, progress.md:5-15