Guides/GitHub PAT Setup

GitHub Personal Access Token Setup

Configure a GitHub Personal Access Token (PAT) to enable repository creation, code sync, and issue management for your Trinity agents.

Concepts

•Personal Access Token (PAT) — A GitHub credential that grants Trinity access to your repositories. Acts as a password for API access.

•Classic Token — The traditional PAT format. Simpler to configure, grants broad access per scope.

•Fine-Grained Token — Newer PAT format. Allows granular permissions on specific repositories.

•Scopes — Permission categories that control what the token can do (read code, write issues, etc.).

When You Need a PAT

Feature	Requires PAT
Create new GitHub repo for an agent	Yes
Push agent code to GitHub	Yes
Pull updates from private repos	Yes
Create/update GitHub Issues from agents	Yes
Clone from public templates	No
Pull from public repos (read-only)	No

The token needs the right scopes for each row above. As of #1574 Trinity wires the managed token for both git and the gh CLI / REST API — but wiring only makes the token available; it can't grant scopes the token lacks. A git-contents-only PAT still 403s on Issues/PRs.

What the PAT Authenticates: Git and the gh CLI (#1574)

When an agent has a GitHub repo and a resolved PAT (per-agent override or the platform PAT), Trinity:

•bakes the token into the agent repo's origin remote URL (https://oauth2:<token>@github.com/...) for git, and

•exposes it inside the container as GITHUB_PAT and GH_TOKEN / GITHUB_TOKEN — the variables the gh CLI and GitHub REST API read.

So both work automatically:

Operation	Auto-authenticated by Trinity's token?
`git` push / pull / clone (agent's own repo)	Yes — token is in the remote URL
`gh issue`, `gh pr`, `gh api`, `gh repo` …	Yes — `GH_TOKEN`/`GITHUB_TOKEN` are set, and `gh` is preinstalled in the base image
GitHub REST API via `curl` / a github MCP server	Yes — `$GITHUB_PAT` (or `$GITHUB_TOKEN`) is in the environment

Inside an agent with a valid PAT you can just run:

gh auth status          # → authenticated
gh issue list -R OWNER/REPO
gh api /user
curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user

No gh auth login, no per-command GH_TOKEN="$GITHUB_PAT" … prefix.

Scopes still matter. A PAT scoped only for git contents can push code but will 403 on Issues/PRs. For issue management, make sure the token carries repo (classic) or Issues: Read and write(fine-grained) — see the scope tables below. Wiring makes the token available; it does not grant missing scopes.

Older agents: the gh binary ships in the agent base image — an agent created before this change picks it up on the next base-image rebuild + recreate. git keeps working regardless; the GH_TOKEN/GITHUB_TOKEN env vars are also injected on the next agent restart/recreate.

Who Owns the Platform PAT

Trinity stores a single platform-wide PAT as the shared fallback. Agent creation resolves a token in three tiers: per-agent override → your personal token → platform global (see Your Personal GitHub Token below). In the standard setup, the Trinity admincreates the platform token in their own GitHub account — which means, for any agent that falls back to it:

•The token's reach is the admin's reach. Anything the admin's GitHub user can do, every agent using the platform PAT can do.

•Agents are hosted under the admin's GitHub account / org for the repos they push to. If an agent needs to push to a repo the admin doesn't have access to, use a personal token or a per-agent PAT override instead.

•The admin's decision up front: how much of their own GitHub access should bleed through to the agents? This is the question that picks classic vs. fine-grained.

Non-admins are no longer confined to the admin PAT's repo scope — anyone can add their own token, resolved ahead of the global fallback.

Your Personal GitHub Token (per-user)

You do not have to rely on the shared platform PAT. Any authenticated user — not just admins — can store their own GitHub token in personal Settings. At agent creation Trinity resolves a token in three tiers:

per-agent override → your personal token → platform global

So a non-admin is no longer confined to the admin PAT's repo scope: an agent you create picks up your token first, reaching the repos your GitHub user can reach.

•Never echoed back. A read returns status only (configured, has_global) — never the token string.

•Validated and encrypted. The token is checked against GitHub before it is saved, then encrypted at rest.

How the resolved token is persisted:

•When the resolved token came from the personal (or fork) tier, it is saved as that agent's per-agent token, so the agent keeps working even if you later change your personal token.

•When the agent fell back to the platform global PAT, it keeps no copy — it stays on the shared token and follows global rotations.

Clearing your personal token reverts future agent creations to the platform global. Already-created agents are unaffected — they keep the copy they were given. Conversely, adding a personal token never force-recreates a running agent; it only changes what new agents resolve.

Endpoints (per-user)

Endpoint	Method	Description
/api/users/me/github-pat	GET	Personal token status only — `{configured, has_global}`; never the token
/api/users/me/github-pat	PUT	Store your personal token (body `{pat}`); validated → 400 rejected / 503 GitHub unreachable; encrypted at rest
/api/users/me/github-pat	DELETE	Remove your personal token (future creations fall back to global)

Full request/response schemas are in the backend's Swagger docs (http://localhost:8000/docs when running locally).

Choosing a Token Type

If you want...	Pick	Tradeoff
Simplest setup; fine with agents inheriting access to every repo your account can reach	Classic PAT	Wider blast radius if the token leaks. New agents work instantly — no GitHub-side steps.
Agents scoped to a specific list of repos, nothing else	Fine-grained PAT	Smaller blast radius. Every time you add an agent on a new repo, you edit the token to include that repo.

Classic is faster to operate. Fine-grained is safer. Pick the tradeoff that matches your organization's risk posture.

Option A: Classic Token (simplest, widest access)

A classic PAT with repo scope grants access to every repository your GitHub user can see— personal repos, plus any org repos your account has access to. Best when you're comfortable with that reach and want zero-maintenance setup.

GitHub new classic personal access token page with the repo scope checked — GitHub new classic personal access token page with the `repo` scope checked.

Step 1: Create the token

Go to github.com/settings/tokens

Click Generate new token → Generate new token (classic)

Set a descriptive name: Trinity Platform

Set expiration (90 days recommended, or "No expiration" for persistent setups)

Select required scopes:

Scope	Required	Purpose
repo	Yes	Full control of repositories
workflow	Optional	Trigger GitHub Actions
read:org	Optional	Read organization membership

Click Generate token

Copy the token immediately — you cannot view it again

Step 2: Configure in Trinity

Go to Settings in Trinity (sidebar → Settings)

Find the GitHub Personal Access Token (PAT) section

Paste your token

Click Test to verify it works

Click Save

Saving auto-propagates to running agents. When the platform PAT changes, Trinity pushes the new token into every running agent's .env file within seconds — no restart required. The save response lists which agents were updated, skipped, or failed. Agents with a per-agent PAT override, or agents that never configured GitHub, are skipped. Per-agent failures are reported but never block the save.

Option B: Fine-Grained Token (scoped, safer, more maintenance)

A fine-grained PAT is limited to a specific list of repositories and a specific set of permissions. Agents can only touch what you listed — not the admin's other repos. Best for production and for admins whose personal GitHub account also holds unrelated work you don't want agents near.

Step 1: Create the token

Go to github.com/settings/tokens?type=beta

Click Generate new token

Set name and expiration

Under Repository access, choose "All repositories" or "Only select repositories"

Under Permissions, expand "Repository permissions" and set:

Permission	Level	Purpose
Contents	Read and write	Push/pull code
Issues	Read and write	Create and manage issues
Metadata	Read-only	Required (auto-selected)
Pull requests	Read and write	Optional: create PRs
Workflows	Read and write	Optional: GitHub Actions

Click Generate token

Copy the token immediately

Choosing Between Token Types

Consideration	Classic Token	Fine-Grained Token
Setup complexity	Simple	More steps
Repository scope	All repos by default	Can limit to specific repos
Permission granularity	Broad scopes	Individual permissions
Token format	ghp_...	github_pat_...
Recommended for	Development, personal use	Production, shared teams

Hosting Agents from External Contributors

A useful consequence of how classic PATs work: a classic PAT reaches every repo its owner can access, including repos that were shared with the owner as a collaborator. This unlocks a simple workflow for letting external agent developers deploy their agents on your Trinity instance without handing over tokens or transferring repos.

The pattern

External developer has their agent code in their own GitHub repo.
They invite the Trinity admin's GitHub user as a collaborator, with role:
- • Write — if the agent needs to push back (Working Branch mode, scheduled commits, etc.). This is the usual case.
- • Read — if the agent only pulls (Source mode / deploy-only).
Admin accepts the invitation.
Trinity's classic PAT now reaches the repo immediately — no token change, no restart. Deploy the agent from that repo like any other.
When the engagement ends, the external developer removes the admin as a collaborator. Access disappears the same moment. The PAT is untouched.

Important caveats

•Only works with classic PATs. A fine-grained PAT is scoped to a single resource owner (one user or one org) and cannot reach a friend's or another org's repositories, regardless of collaborator status. If you're running fine-grained, use a per-agent PAT override instead — the external developer creates their own fine-grained PAT scoped to their repo and you paste it as the agent's override.

•SSO-protected orgs. If the shared repo lives inside an org that enforces SAML SSO, the admin's classic token must be SSO-authorized for that org (token settings → Configure SSO → Authorize). Otherwise Git operations fail even though the admin user can see the repo in the browser.

•Admin's role caps what the PAT can do. If the admin was invited with Read, pushes fail with 403 regardless of what the classic PAT's scopes allow.

•Blast radius still applies. The classic PAT can reach all repos the admin has collaborator access to — not just the one you intended to deploy. If that's a concern, use a per-agent PAT override instead so each external agent brings its own scoped token.

Updating the Token Later

Most edits to an existing PAT happen in-place in GitHub — the token string stays the same, so you do not need to paste a new token into Trinity. The main exceptions are regenerating, rotating, or (for fine-grained tokens) changing permissions in ways that may require org re-approval.

Fine-grained PAT — editable in-place

• Repository list — adding or removing repos. Common when you deploy a new agent that needs access to a repo not in the original list.
• Expiration date — extend or shorten.
• Name / description.

Fine-grained PAT — when to regenerate

• Permission changes (e.g. adding Issues: Read and write) — the UI may let you save permission changes in-place, but org PAT policies can require re-approval and some deployments see inconsistent behavior. Safest path: regenerate the token and paste the new one into Trinity Settings. If the token is on a personal account with no org policy, in-place editing usually works; you can try it first.
• Token lost / suspected compromise — always regenerate.

Classic PAT

• Scopes are editable in-place (check/uncheck boxes and save).
• The token string itself only changes if you click Regenerate.

After any change that produces a new token string, update it in Trinity via Settings → GitHub Personal Access Token → Test → Save. Trinity propagates the new token to every running agent that uses the platform PAT within seconds — the container environment, the workspace .env, and the git credential configuration are all updated, so a rotation takes effect for the agent's next push without a manual restart.

Agents that carry their ownper-agent token are deliberately untouched by a global rotation — update those on the agent's Git tab.

API

Endpoint	Method	Description
/api/settings/api-keys	GET	Check PAT status
/api/settings/api-keys/github/test	POST	Test a PAT
/api/settings/api-keys/github	PUT	Save PAT

MCP tool: initialize_github_sync(agent_name, repo_url) uses the configured PAT.

Troubleshooting

"Resource not accessible by personal access token"

Cause: Token lacks required permissions.
Fix (Classic): Regenerate with repo scope checked.
Fix (Fine-Grained):Add "Contents: Read and write" permission.

"SSO authorization required"

Cause:Organization uses SAML SSO and the token isn't authorized.
Fix: Go to github.com/settings/tokens, find your token, click Configure SSO, and authorize for the organization.

"Bad credentials" error

Cause: Token is expired, revoked, or mistyped.
Fix: Generate a new token and reconfigure in Trinity Settings.

Security Best Practices

•Use fine-grained tokens in production — Limit blast radius if token is compromised

•Set expiration dates — 90 days is a reasonable balance

•Use separate tokens per environment — Dev and prod should have different tokens

•Never commit tokens to git — Trinity stores the PAT in the database, not in code

•Revoke unused tokens — Clean up old tokens at github.com/settings/tokens

Limitations

•Trinity stores one platform-wide GitHub PAT as the shared fallback. At creation an agent resolves per-agent override → the owner's personal token → platform global, so agents share the global PAT only when neither higher tier is set.

•Fine-grained tokens require GitHub to be configured to allow them (enabled by default for personal accounts).

•Organization-owned fine-grained tokens require org admin approval.

•PAT propagation targets only currently-running agents. Stopped agents receive the updated PAT on next start.

•See Updating the Token Later above for what can be edited in-place vs. what requires regenerating the token.

GitHub Personal Access Token Setup

Concepts

When You Need a PAT

What the PAT Authenticates: Git and the gh CLI (#1574)

Who Owns the Platform PAT

Your Personal GitHub Token (per-user)

Endpoints (per-user)

Choosing a Token Type

Option A: Classic Token (simplest, widest access)

Step 1: Create the token

Step 2: Configure in Trinity

Option B: Fine-Grained Token (scoped, safer, more maintenance)

Step 1: Create the token

Choosing Between Token Types

Hosting Agents from External Contributors

The pattern

Important caveats

Updating the Token Later

Fine-grained PAT — editable in-place

Fine-grained PAT — when to regenerate

Classic PAT

API

Troubleshooting

"Resource not accessible by personal access token"

"SSO authorization required"

"Bad credentials" error

Security Best Practices

Limitations

See Also

Trinity docs

GitHub references