Skip to main content
Trinity
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

FeatureRequires PAT
Create new GitHub repo for an agentYes
Push agent code to GitHubYes
Pull updates from private reposYes
Create/update GitHub Issues from agentsYes
Clone from public templatesNo
Pull from public repos (read-only)No

Who Owns the Platform PAT

Trinity stores a single platform-wide PAT that every agent inherits unless an agent has its own per-agent override. In the standard setup, the Trinity admincreates this token in their own GitHub account — which means:

•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 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.

Choosing a Token Type

If you want...PickTradeoff
Simplest setup; fine with agents inheriting access to every repo your account can reachClassic PATWider blast radius if the token leaks. New agents work instantly — no GitHub-side steps.
Agents scoped to a specific list of repos, nothing elseFine-grained PATSmaller 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

1

Go to github.com/settings/tokens

2

Click Generate new token → Generate new token (classic)

3

Set a descriptive name: Trinity Platform

4

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

5

Select required scopes:

ScopeRequiredPurpose
repoYesFull control of repositories
workflowOptionalTrigger GitHub Actions
read:orgOptionalRead organization membership
6

Click Generate token

7

Copy the token immediately — you cannot view it again

Step 2: Configure in Trinity

1

Go to Settings in Trinity (sidebar → Settings)

2

Find the GitHub Personal Access Token (PAT) section

3

Paste your token

4

Click Test to verify it works

5

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

1

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

2

Click Generate new token

3

Set name and expiration

4

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

5

Under Permissions, expand "Repository permissions" and set:

PermissionLevelPurpose
ContentsRead and writePush/pull code
IssuesRead and writeCreate and manage issues
MetadataRead-onlyRequired (auto-selected)
Pull requestsRead and writeOptional: create PRs
WorkflowsRead and writeOptional: GitHub Actions
6

Click Generate token

7

Copy the token immediately

Choosing Between Token Types

ConsiderationClassic TokenFine-Grained Token
Setup complexitySimpleMore steps
Repository scopeAll repos by defaultCan limit to specific repos
Permission granularityBroad scopesIndividual permissions
Token formatghp_...github_pat_...
Recommended forDevelopment, personal useProduction, 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

  1. External developer has their agent code in their own GitHub repo.
  2. 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).
  3. Admin accepts the invitation.
  4. Trinity's classic PAT now reaches the repo immediately — no token change, no restart. Deploy the agent from that repo like any other.
  5. 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 auto-propagates the new token to all running agents that use the platform PAT within seconds.

API

EndpointMethodDescription
/api/settings/api-keysGETCheck PAT status
/api/settings/api-keys/github/testPOSTTest a PAT
/api/settings/api-keys/githubPUTSave 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. All agents share it unless overridden per-agent.
•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.

See Also

Trinity docs

GitHub references

Agent GuardrailsTelegram Integration