Skip to main content
Experimental version.This is the latest in-development version of AI-Implement. Features may change without notice and behavior is not guaranteed. Switch to the latest stable version here.
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 the selected agent, 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

Pull request creation setting (not required)

The Allow GitHub Actions to create and approve pull requests setting is at Settings → Actions → General in the target repo.This setting is not required. Every synced workflow opens pull requests with a GitHub App token, which this setting does not govern.Leaving the setting on does no harm.
3

Set up the trigger in your ticketing system

Prepare the Linear labels before your first run. Create the pickup label (AI-Implement by default) and the workspace-level Ready for Review label. AI-Implement creates the other lifecycle labels automatically.
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. 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.
For the Codex path, select GitHub Actions as the runner, complete the remaining fields, then click 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 implementation prompt template
  • PLANNING.md — the 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.
6

Configure Codex for the saved project

Check that the runner image supports Codex. If you are connecting an existing project, use Sync workflows on Projects and merge that update first.Next, follow Use Codex with OpenAI to create a managed account profile, permit it for this project, and add an API key or connect your own ChatGPT plan.Follow Agent settings per stage to set the orchestrator defaults and enable configured defaults mode. Open the saved project’s Edit → Agents tab, check all three effective stages, select Opt in to stage agent configuration, and click Save agent settings.An all-Codex configured project needs no Anthropic repository secret. Skip this step to keep legacy Claude behavior with its existing provider credentials.
7

Trigger a run and watch it

Apply the AI-Implement label to any Linear issue in the mapped team.
On the next eligible poll, the orchestrator picks it up and dispatches the workflow. The selected planning agent runs first if planning is enabled, followed by the implementation agent.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. Describe what should change and why, with acceptance criteria the agent can verify.

​
Jira: manual custom-field setup

Linear users can skip this section — use the Linear label setup instead. 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, verify the agent, model, and result. Reports → Agent attribution shows the latest invocation per job, not whole-job usage or cost. An unavailable cost is not zero. You can then:
  • Read the post-push review on the PR — a GitHub review with a Full reviewer report link and a sticky status comment on merge readiness
  • Comment /ai-implement on the PR to send the implementation agent 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.

Customize WORKFLOW.md

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

Admin UI reference

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