Skip to main content
Connecting a GitHub repository to AI-Implement comes down to adding a project mapping in the orchestrator’s admin UI. Saving it opens a pull request carrying the workflow templates, and starts the orchestrator polling for issues. Runs can only dispatch once that pull request is merged, so follow the steps below in order.
1

Install the GitHub App on the target repo

If you did not install the GitHub App on all repositories during the GitHub App setup, install it on this repo now. Go to your GitHub App’s settings page, open the Install App tab, and add the target repo to the App’s installation.
2

Set up the trigger in your ticketing system

In your Linear workspace, create a label named AI-Implement.You can create labels from Settings → Labels in your Linear workspace. The orchestrator makes the per-team labels it applies during a run — AI-Working, AI-Planning and Plan-Complete — the first time it needs them.
Ready for Review is the one label the orchestrator cannot create for you: it is workspace-level, and an application identity is not permitted to add one. Create it by hand before your first run — Prepare the Ready for Review label covers it.Without it, a finished run leaves the issue holding AI-Working, with no Ready for Review and no pull-request comment, so the issue looks like it is still going.
Ensure the triggers are entered exactly as written. The orchestrator matches on those exact strings — capitalization matters.
3

Create a project mapping in the admin UI

Open the admin UI at http://localhost:8080/admin (or your Fly.io app URL) and click Configure → Projects → + New project. For a first connection, the key inputs are:
  • Ticketing System — Linear
  • Ticketing Config → Linear Team Key — your Linear team key (e.g. ENG)
  • Source → GitHub Owner — the GitHub org or user that owns the target repo
  • Source → Repository Name — the target repository’s name without the owner prefix
  • Source → Default Branch — the repo’s primary branch (e.g. main). Must match the repo exactly.
Nothing checks the default branch name against the repository when you save. A default branch name that does not exist saves cleanly and fails the run at its first step, when the runner tries to clone it.
Step through the remaining steps accepting defaults for a first run, then Create project. The orchestrator begins watching the configured scope on its next poll cycle.See the Admin UI reference for the full field list and defaults.
4

Review and merge the workflow pull request

Saving the project opens a pull request in the target repo that adds the following files to .github/workflows/ and the repo root:
  • claude-implement.yml — the main implementation workflow
  • claude-plan.yml — the planning workflow
  • WORKFLOW.md — the Claude implementation prompt template
  • PLANNING.md — the Claude planning prompt template
WORKFLOW.md and PLANNING.md are seeded once and never overwritten by subsequent syncs. After the initial setup, each repo owns its own prompt templates — you can edit them freely without them being reset by a future sync.
Open the pull request that was created in your target repo and review the added files. Merge the PR when you are ready. Once merged, the workflow files are active and GitHub Actions can dispatch runs against that repo.
5

Trigger a run and watch it

Apply the AI-Implement label to any Linear issue in the mapped team.
Within 60 seconds (one poll cycle), the orchestrator picks it up, dispatches the workflow, and Claude Code starts working on the implementation.When the run finishes, the issue is marked ready for review (Linear: Ready for Review label added; Jira: AI-Implement Status set to PR Ready), with a comment linking to the PR.
For best results, target issues that are focused and well-specified. Claude performs well on issues that clearly describe what should change and why — and less well on vague or sprawling tickets.

​
Jira: manual custom-field setup

Linear users can skip this section — the orchestrator auto-creates Linear labels on first use, but Jira custom fields must exist before the orchestrator can pick up any issue. AI-Implement requires two custom select fields in your Jira instance: one for the run lifecycle status, AI-Implement Status, and one for scoping issues to a target repo, AI-Implement Repo.
1

Create the AI-Implement Status custom field

In Jira, navigate to Settings → Issues → Custom fields → Create custom field. Choose Select List (single choice) and name the field exactly AI-Implement Status.Add the following options. Order doesn’t matter to the orchestrator, but the spellings do:
  • Ready
  • Planning
  • Plan Approved
  • Implementing
  • PR Ready
  • Planning Failed
  • Implementation Failed
  • Merged
Field name and option spellings must be exact — the orchestrator matches them literally. A typo will surface as either a missing-field error at startup or as issues silently not getting picked up.
2

Create the AI-Implement Repo custom field

Create a second Select List (single choice) custom field named exactly AI-Implement Repo.Add one option per target repo you intend to connect, using a convention you’ll keep consistent across mappings (e.g. your-org/backend, your-org/api). Each option’s value becomes the Repo Field Value you’ll enter in the admin UI’s project mapping.
3

Add both fields to your project's screens

Both fields must appear on the create, edit, and view screens of the Jira project(s) where you’ll use AI-Implement, so users can set their values.Go to Project settings → Screens (or the equivalent for your project’s screen scheme) and add both AI-Implement Status and AI-Implement Repo to the relevant screens.
4

(Optional) Note the field IDs for explicit overrides

Most installations don’t need this step — the orchestrator auto-discovers both fields by name. You only need explicit field IDs when your Jira instance has multiple fields sharing one of these names (e.g. left over from another tool).To find a field’s ID, hover over the field name in the custom-fields admin list and Jira shows the URL containing customfield_NNNNN. The Jira REST GET /rest/api/3/field endpoint also returns every field with its ID. You’ll paste these into the optional Status Field Override / Repo Field Override inputs on the admin UI’s Ticketing Config step.
One more field is available to you if you customize the pipeline. AI-Implement Profiles lets an issue carry names that your own custom pipeline steps branch on, and nothing built in reads it — so add it only once you have a step that wants it.Create it as a Select List (multiple choices) named exactly that, add one option per name you want to select from, and put it on the same screens as the other two.

​
After your first run

Once the PR appears, you can:
  • Review the automated review comment that Claude posts automatically, showing whether the PR is ready to merge and what (if anything) still needs attention
  • Comment /ai-implement on the PR to send Claude back in for a gap-fill pass on the same branch
  • Merge the PR to close the issue.
Merging the PR closes the issue for you — the orchestrator moves Linear issues to Done and sets Jira’s AI-Implement Status to Merged.No Fixes reference or Jira automation is needed.
From here you can add a capability the orchestrator runs fine without, or go deeper on what you already have:

Admin sign-in

Per-person sign-in in place of a shared access code.

Self-deployment

Let the orchestrator build and release its own updates.

Knowledge graph

Project memory the BuildDown skills search before they plan.

Customize WORKFLOW.md

Edit the Claude prompt template to match your repo’s stack and conventions.

Admin UI reference

Full reference for all fields available in the project mapping form.