# GitHub runs

Sessions run on **your laptop** by default: your own sign-in, no keys, nothing to set up on GitHub. Pick **Runs on → GitHub** in the composer's session settings when you want the agent to run in GitHub Actions instead. That needs a one-time setup in the repository, done by someone with **admin** access.

The fastest way: paste the [GitHub runs setup prompt](/docs/settings/github-runs-prompt) into your coding agent from the repository's folder. In Claude Code, once This laptop is set up, `/ikanban-github-runs-setup` does the same. It checks everything, asks before each change, and never sees your token or key.

## What each agent needs

**Claude**
1. Install the [Claude GitHub App](https://github.com/apps/claude) on the repository.
2. Run `claude setup-token` (Claude Pro, Max, Team or Enterprise) and save the token as the repository secret `CLAUDE_CODE_OAUTH_TOKEN`:
   ```bash
   gh secret set CLAUDE_CODE_OAUTH_TOKEN -R <owner>/<repo>
   ```
   The token works from any machine, like a password for your Claude plan. Never paste it into a chat or a file; if it leaks, make a new one and set it again.
3. Add iKanban's Claude workflow as `.github/workflows/claude.yml`. Set up on **This laptop** puts it in your repository at `.iKanban/github/claude.yml`.

**Gemini**
1. Create a key at [Google AI Studio](https://aistudio.google.com/apikey) and save it as `GOOGLE_API_KEY`:
   ```bash
   gh secret set GOOGLE_API_KEY -R <owner>/<repo>
   ```
2. Add credits in AI Studio → **Billing**. The free tier for the model the CLI uses is 0.
3. Add iKanban's Gemini workflow as `.github/workflows/gemini.yml` (from `.iKanban/github/gemini.yml`). Google's own Gemini workflow listens for `@gemini-cli`, so it doesn't react to iKanban's `@gemini` issues.

**Copilot**
- No file and no key. An organization owner opens the organization's **Settings → Copilot → Cloud agent**, sets the policy to **Enabled**, and includes the repository under **Repository access**. You need a **Copilot Business or Enterprise** license from that organization. [GitHub's steps](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-organization/add-copilot-coding-agent).

**Claude and Gemini: let the workflow open the pull request.** A repository admin opens **Settings → Actions → General → Workflow permissions**, ticks **Allow GitHub Actions to create and approve pull requests**, and saves. If the box is grey, the organization locks it: an organization owner first ticks the same box under **Organization settings → Actions → General → Workflow permissions**. Without it the agent's branch is pushed but no pull request opens ("GitHub Actions is not permitted to create or approve pull requests"). If automations should merge the agent's pull requests, also set the repository variable **IKANBAN_CI_WORKFLOW** to your CI workflow's file name (with a `workflow_dispatch` trigger), so the pull request gets checks: see **Docs → Automations**.

**Then:** merge the workflow files into the default branch. GitHub runs issue workflows only from there.

## Check it
Start a session with **Runs on → GitHub** and the agent you set up: *"reply with a one-line summary of this repository; don't change files"*. The session page links the GitHub issue, then shows **Done** with the answer.

## When a run fails

| The session says | Fix |
| --- | --- |
| The agent pushed a branch but no pull request opened | Tick **Allow GitHub Actions to create and approve pull requests** (Settings → Actions → General) |
| Claude stopped within a second, no answer | The token is missing or expired: run `claude setup-token` and set the secret again |
| The repository secret GOOGLE_API_KEY isn't set | Add the Gemini key (above) |
| Google refused Gemini: credits used up or quota 0 | Add credits in Google AI Studio → Billing (aistudio.google.com), then try again |
| Copilot cloud agent isn't enabled | An organization owner turns it on (above) |
| Nothing happens on the GitHub issue | The workflow isn't on the default branch yet, or Actions are turned off in the repository's settings |

Your secrets stay in GitHub. iKanban never reads them, and laptop sessions never use them.