AgentLayer▸docs
Connect it

GitHub

Pull requests, issues and CI runs through eighteen tools, on one token per repo owner. Read-only unless your token allows a write, and nothing merges or closes.

The GitHub pack lets your agent read pull requests, issues and GitHub Actions runs, keep your checkouts current, and make the few writes your token allows. It has no skill of its own. The engineer skill's pull-request playbooks and adversarial-review run on it.

What it gives you

Eighteen tools that wrap the gh CLI. MCP tools lists each one.

What the agent can do
ReadPull requests with their inline review comments, diffs and checks. Workflow runs and the logs of failed steps. Issues. And github_sweep: everything waiting on you across your PRs, reviews and issues
Refreshgithub_fast_forward fast-forwards your local default branches during sync. It never resolves a dirty, diverged or worktree-held branch; it reports it
WriteOpen, edit, comment on and label issues, open a pull request from a pushed branch, replace a PR's title or description, and fix its own comment. See Writes

Nothing merges, closes or re-runs a workflow, and nothing edits someone else's comment.

When a call names no repo, the agent takes it from the origin remote of AGENT_CODE_PATH, then from the first AGENT_GIT_REPOS entry. An explicit repo="owner/repo" always wins.

What it needs

NeedDetail
The gh CLIEvery tool runs it. On a Mac: brew install gh. Elsewhere: cli.github.com
A token per repo ownerA fine-grained personal access token reaches one org's or one user's repos only, so each owner gets its own
CostFree

Tokens live in the secrets store, and every tool picks the one for the repo it is called on:

  1. GITHUB_TOKEN_<OWNER>: the owner's login in capitals, hyphens as underscores (my-org becomes GITHUB_TOKEN_MY_ORG).
  2. GITHUB_TOKEN: an optional catch-all for any owner without a key of its own.
  3. Neither: your own gh auth login. The sync fast-forward skips that repo.

Switch it on

Run the walk

Run configure-skills and pick GitHub. It grants the tools, lists the owners behind your checkouts, and tells you which token lines to add.

Create a token for each owner

At GitHub → Settings → Developer settings → Fine-grained tokens, choose Generate new token:

  • Resource owner: that owner (your org, or your own account).
  • Repository access: the repos the agent should reach, as few as the work needs.
  • Repository permissions, all Read-only: Pull requests · Issues · Metadata · Actions · Contents.

For writes, raise only what the agent should change (Writes). With read-only permissions the pack stays read-only.

Add the tokens in your editor

One line per owner in <HOME>/.state/secrets/.env, never in chat:

GITHUB_TOKEN_MY_ORG=github_pat_...
GITHUB_TOKEN_MY_LOGIN=github_pat_...
GITHUB_TOKEN=github_pat_...   # optional catch-all

Relaunch

Start your host again from the home so the tokens load.

Two permission gotchas

Grant Actions: Read (workflow runs and logs). Do not grant Workflows: despite the name it is write access to the workflow files. Contents: Read is required for git fetch and diffs and grants no push ability. There is no Checks permission for fine-grained tokens, so github_pr_checks returns 403 where CI reports as check runs; read build state from the run tools instead.

An org that approves tokens first. An org can require approval before a fine-grained token reaches its repos. Until it approves, put a classic token under that owner's key instead, with repo, read:org, read:user and user:email and an expiry date. A classic token reaches every repo your account can, not one owner's.

gh in the agent's own shell is blocked. Switching the pack on adds Bash(gh) and Bash(gh *) to permissions.deny, and a forbidden rule to a Codex home's .codex/rules/agentlayer.rules. GitHub is then reached only through these tools, under the token picked for each repo. Your own terminal is not affected.

Writes

Six tools make the writes: issues, comments, a PR's title and description, a fix to the agent's own comment, and opening a PR, which always waits for you.

Nothing closes an issue or edits someone else's comment.

These writes let one agent hand work to another. A support agent opens a bug and the owner labels it. The engineer's agent builds what was accepted, moves it to in progress when work starts, and sets its milestone to the release it ships in when the fix is done.

Writes run on the same per-owner token as the reads, and the token's permissions decide what they may do:

ToGive the owner's token
Open, edit, comment on and label issuesIssues: Read and write
Open a PR, or change its title or descriptionPull requests: Read and write

A write the token isn't allowed fails with a message that names the permission to add. An owner with no token runs as your own gh auth login, limited by your role on the repo.

A few limits apply: your role on the repo, the attachment types and sizes, and labels and milestones that must already exist.

Where it's used

The engineering playbooks, sync, the helpdesk and tasks all run on this pack.

On this page