Skip to main content
AI-Implement uses a GitHub App — not a personal access token — to authenticate workflow dispatches and to open pull requests. Using an App identity is what makes the /ai-implement comment trigger work correctly: the PR is opened by the bot, so subsequent comments on it can be reliably attributed and re-dispatched.

​
Create the GitHub App

1

Open the GitHub App creation page

Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App.If you want the App to be owned by a GitHub organization rather than your personal account, navigate to your organization’s settings page first, then go to Developer settings → GitHub Apps → New GitHub App.
You can transfer App ownership between personal accounts and organizations if desired, so either creation method will work for initial setup.
2

Name the App and set the homepage URL

Give the App a name such as ai-implement-bot. The name appears in PR authorship and comment attribution, so choose something your team will recognize.Set the homepage URL to any valid URL — for example, the AI-Implement GitHub repository https://github.com/BuildDownAI/AI-Implement.
3

Set repository permissions

Under Repository permissions, configure the following:Leave all other permissions at their defaults (no access).
Both Actions and Workflows permissions are needed for GitHub Actions to function. Workflows allows sync-workflow.yml to write workflows to target repos, and Actions allows the orchestrator to run those workflows.
4

Configure webhook delivery

Webhook delivery is optional for the core run loop — issues still get picked up, runs still dispatch, pull requests still open, and merging one still marks the issue done, all on the poll cycle alone.But skipping it disables two things with no fallback: automatic follow-up runs on review feedback (when a reviewer leaves blocking comments, AI-Implement normally sends Claude back in without anyone commenting /ai-implement), and the /ai-implement comment trigger itself on repos synced to the current workflow templates — the orchestrator’s webhook is the only thing that listens for that comment on such a repo, so without it, commenting /ai-implement does nothing.
Uncheck Webhook active. The event list disappears and there’s nothing else to set here./ai-implement and automatic review-feedback follow-ups won’t work without a later webhook setup — plan on revisiting this if you need either.
5

Choose where the App can be installed

Under Where can this GitHub App be installed?, select Only on this account if you want to restrict the App to your own organization. Select Any account if you plan to install it across multiple organizations.
If a personal account creates an App intended for an organization, you must select Any account — otherwise the org cannot install it.
6

Create the App and note the App ID

Click Create GitHub App. On the resulting page, note the App ID — you will need it as AI_IMPLEMENT_APP_ID (for the workflow secrets) and as GITHUB_APP_ID (for the orchestrator).
7

Generate a private key

Scroll to the Private keys section and click Generate a private key. GitHub downloads a .pem file to your computer.Keep this file secure. You will paste its contents as the AI_IMPLEMENT_PRIVATE_KEY secret in your target repos and as the GITHUB_APP_PRIVATE_KEY variable in the orchestrator.
The private key grants full access to everything the App is installed on. Store it in a secrets manager or environment variable, never in source control.
8

Install the App on your target repos

Go to the App’s Install App tab and install it on the GitHub organization or personal account that owns your target repositories. You can choose All repositories or restrict to specific repos — install it on at least the repos you intend to connect to AI-Implement.

​
Add secrets to your target repos

The workflow templates that AI-Implement syncs into target repos read the following secrets. Add them at the organization level (recommended) so all target repos inherit them, or add them individually per repo under Settings → Secrets and variables → Actions. Each secret below notes its counterpart on the orchestrator where the names differ. See Environment variables for the full set, including the ones that live only on the orchestrator.
CLAUDE_CODE_OAUTH_TOKEN takes precedence over ANTHROPIC_API_KEY when both secrets are set. You only need one Claude authentication method, but having both configured gives you a fallback.

​
Enable pull request creation in target repos

Each target repo must allow GitHub Actions to create and approve pull requests. Without this setting, the workflow will fail when it tries to open the PR. In each target repo, go to Settings → Actions → General and enable Allow GitHub Actions to create and approve pull requests.
This setting must be enabled in every repo you connect to AI-Implement. It is not inherited from organization-level settings.

​
What’s next

Deploy the orchestrator

Run the orchestrator on Fly.io or locally with the credentials you just created.

Connect a target repo

Sync workflow templates into a repo and map it to a Linear team.