Set up GitHub issue integration

The single highest-leverage automation in CodeCourier is the one that eliminates the manual step between "ticket exists in GitHub" and "agent is working on it". This 15-minute setup is the difference between a tool you have to remember to use and a tool that just shows up.

1. Install the GitHub app

In the CodeCourier dashboard, open Integrations → GitHub and click Install GitHub App. Choose the org you want to connect and grant the minimum scopes: repository contents (read + pull-request-create), issues (read + write), and webhook events.

On the GitHub side, select either "All repositories" or a specific list. Start with one or two repos for the first run; you can expand later without re-installing.

2. Pick a trigger label

CodeCourier listens for a label being applied. Pick a label name that is obviously not a regular triage label - we recommend codecourier:run. Create it in each connected repo.

# create the label on a repo
gh label create "codecourier:run" \
  --description "Hand this issue to CodeCourier" \
  --color "00CAE5"

The cyan colour is a small touch but matters: it makes the label visually distinct from priority and triage labels at a glance.

3. Map labels to personas

In the integration settings, define a mapping from GitHub label to CodeCourier persona. This is where you encode policy without writing code.

• codecourier:run → default persona for that repo.
• codecourier:frontend → Frontend Specialist persona.
• codecourier:backend → Backend Specialist persona.
• codecourier:investigate → Researcher persona (read-only session that emits a comment, no PR).

4. Wire the state sync

Enable two-way state sync in the integration settings. Now an Issue Session marked as in-progress in CodeCourier sets the GitHub issue to in progress, and a merged PR closes the issue automatically. Closing the issue manually on GitHub cancels any active session, so the human override always wins.

State sync is what makes the integration feel native rather than duct-taped. Without it your team will keep two open tabs.

5. Test with a known issue

Pick an existing open issue you have already triaged manually. Slap codecourier:runon it. Within a few seconds you should see an Issue Session appear in the CodeCourier dashboard, a comment on the GitHub issue linking back, and the issue's status flip to in progress.

Wait for the session to finish, review the resulting pull request, and merge. The issue should auto-close on merge.

6. Add a safety net

In the integration settings, set a per-day budget cap. New users should start at $50/day per repo. This caps the blast radius if someone accidentally bulk-labels a thousand issues at once - and someone will, eventually.

7. Next steps

Once the integration is humming, the obvious upgrades are: wire Sprint Chains to triggered runs so a single label can launch a multi-step pipeline, and read the operations handbook before enabling the integration across your full org.