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 that mapping syncs the workflow templates into the repo so GitHub Actions knows how to run Claude, and starts the polling loop watching for issues. 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

Enable pull request creation in the target repo

In the target repo, go to Settings → Actions → General and enable Allow GitHub Actions to create and approve pull requests.Without this setting, the implementation workflow will fail when it attempts to open a PR.
This setting must be enabled in every repo you connect to AI-Implement, even if it is already enabled at the organization level.
3

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 auto-creates the in-progress labels (AI-Working, AI-Planning, Plan-Complete) on first use, plus Ready for Review workspace-wide.
Ensure the triggers are entered exactly as written. The orchestrator matches on those exact strings — capitalization matters.
4

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. The stepper walks through 8 steps; 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; saving fails with a clear error if the branch doesn’t exist.
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.
5

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.
The /ai-implement PR-comment trigger isn’t a synced workflow file — the orchestrator itself handles it directly, once its GitHub App webhook is configured. See Create a GitHub App.
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.
6

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.

​
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.

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.