Github

GitHub

The user's GitHub token lives in the ranch per-user secret vault — set once via the admin UI, resolved lazily by the runtime on each tool invocation. Agents see it as the environment variable GITHUB_TOKEN.

Same setup mechanics as [[openai]] — load that skill first for the secret-vault flow. This file covers GitHub-specific usage.

Quick Reference

Setting up

1. Go to https://github.com/settings/tokens?type=beta and create a fine-grained personal access token.
2. Scope it narrowly: pick the specific repos and grant only what the agent needs.
3. Open the admin UI at /integrations → GitHub → paste the github_pat_… (or ghp_… for classic) token.

Use multiple accountKeys (personal, work, agency-acme) when the user juggles separate identities — each has its own row and the agent picks via the alias.

Token scopes by task

Don't grant admin:repo_hook or delete:packages unless the agent specifically needs them.

Step 0 — discover the account, never guess

const { accounts } = await integration_list()
const gh = accounts.find(a => a.service === 'github')
if (!gh) {
  return ctx.send(
    "GitHub isn't connected. Open /integrations and add a GitHub token first.",
  )
}

const { env } = await integration_secrets({ service: 'github', accountKey: gh.accountKey })
const token = env.GITHUB_TOKEN

If the user has multiple GitHub accounts connected (e.g. personal + work), pick deliberately via the alias: env.GITHUB_TOKEN_WORK. Most-recently-updated wins the bare GITHUB_TOKEN.

Two call styles — REST or gh CLI

The agent has two ways to hit GitHub. Pick per task:

The REST API is the default — it works the same on every host, doesn't depend on gh being installed, and returns structured JSON. Reach for gh only when you genuinely need git context that the API can't give you alone.

Universal headers helper

const headers = {
  Authorization: `Bearer ${token}`,
  Accept: 'application/vnd.github+json',
  'X-GitHub-Api-Version': '2022-11-28',
  'User-Agent': 'ranch-agent',  // GitHub rejects requests without UA
}

User-Agent is mandatory on the GitHub API. Requests without it return 403.

Capability map — what this skill teaches

Each capability has a dedicated reference document. Load the one matching the current task.

Common patterns

Pagination

Most list endpoints cap at per_page=100. Walk the Link: …rel="next" header until it's gone:

async function paginate<T>(url: string, headers: Record<string, string>): Promise<T[]> {
  const out: T[] = []
  let next: string | null = `${url}${url.includes('?') ? '&' : '?'}per_page=100`
  while (next) {
    const res = await http({ method: 'GET', url: next, headers })
    out.push(...(res.body as T[]))
    const link = res.headers['link'] as string | undefined
    const match = link?.match(/<([^>]+)>;\s*rel="next"/)
    next = match ? match[1] : null
  }
  return out
}

Rate limits

Before a burst of writes, check GET /rate_limit. On 403 + X-RateLimit-Remaining: 0, sleep until X-RateLimit-Reset (unix seconds) — don't retry blindly.

Conditional requests (free reads)

Pass If-None-Match: <etag> from a prior response. A 304 Not Modified doesn't count against the rate limit. Worth doing for any polling loop (Actions status, PR state, etc.).

Error handling

Idempotency

GitHub mutating endpoints are NOT idempotent. Creating the same repo twice is a 422 error, not a no-op. Always check existence first with a GET when retrying.

End-to-end example: create → optimize → release

A common composite task. The agent should do these in order and ask the user to confirm at each handoff:

1. Create the repo from the user's description (create-repo.md).
2. Push initial code (the agent's working tree, or a scaffold).
3. Optimize the About section, topics, README badges, license, social preview (optimize-repo.md). Suggest improvements with explicit before/after diffs and wait for user approval before applying.
4. Verify Actions if a CI workflow exists (check-actions.md).
5. Cut v0.1.0 when the user is ready (release.md).

Don't fold these into one autonomous run unless the user explicitly asked for it. SEO-style edits to a repo are visible to the public — pause for approval on each change.

Don't

• Don't grant admin:repo_hook or delete:packages unless the agent's job specifically requires them.
• Don't reuse a single PAT across multiple users — each user must have their own. The per-user secret store enforces this.
• Don't use classic PATs when fine-grained tokens work. Fine-grained ones can be scoped to specific repos and rotate cleanly.
• Don't echo the token in chat output, logs, or error messages. Filter Authorization headers before logging requests.
• Don't omit the User-Agent header — GitHub returns 403 without it.
• Don't burst writes — 403 secondary rate limit triggers a per-account cooldown that can last hours.
• Don't take destructive actions (delete repo, force-push to default branch, delete release, mark PR as ready/merge) without explicit user confirmation in the same conversation.
• Don't trust the agent's narration that "the PR is merged" — verify by re-reading GET /pulls/{n} and checking merged: true.

References

• GitHub REST API docs
• GitHub CLI manual
• Authentication & scopes
• Rate limits
• Fine-grained PAT permissions table
• Community profile metric
• Auto-generated release notes config