GitHub Setup Guide
Prerequisites
- An active GitHub account with access to the organization(s) and repositories you want to sync, and permission to create Personal Access Tokens for them.
Note: GitHub enforces a rate limit of 5,000 requests/hour per account, not per token - all personal access tokens from the same GitHub account share one quota, so generating several tokens on the same account will not raise the limit. If you're syncing a large organization (many repositories or a high commit volume), add tokens from multiple different GitHub accounts in Matia - see Step 2 below.
Setup Guide
Step 1: Obtain a GitHub Personal Access Token
You can use either a classic or a fine-grained personal access token. Use Option A if you want to sync several GitHub organizations in one connection, or if you need the team, team_membership, or copilot_metric_team streams.
Option A: Classic token
- Sign in to GitHub.
- Click your profile photo in the top-right corner, then click Settings.
- In the left sidebar, click Developer settings.
- Click Personal access tokens → Tokens (classic).
- Click Generate new token → Generate new token (classic).
- Enter a descriptive Note, e.g.
Matia Integration. - Set an Expiration for the token.
- Under Select scopes, check repo, read:org, and read:project.
- Click Generate token.
- Copy the generated token now - GitHub will not show it again.
Option B: Fine-grained token
- Sign in to GitHub.
- Click your profile photo in the top-right corner, then click Settings.
- In the left sidebar, click Developer settings.
- Click Personal access tokens → Fine-grained tokens, then click Generate new token.
- Enter a descriptive Token name, e.g.
Matia Integration, and set an Expiration. - Under Resource owner, select the organization you want to sync.
- Under Repository access, select All repositories or Only select repositories.
- Grant the permissions listed in the Permissions by stream table below. All of them are Read-only.
- Click Generate token. If your organization requires approval for fine-grained tokens, an organization owner must approve the token before Matia can use it.
- Copy the generated token now - GitHub will not show it again.
Note: A fine-grained token can only access a single resource owner. To sync several GitHub organizations with fine-grained tokens, create one Matia connection per organization.
Tip: To avoid rate limiting on large syncs, repeat Step 1 to generate additional tokens - ideally from 4-5 different GitHub accounts with access to the same repositories - and add all of them in Matia in Step 2. Matia will rotate across the provided tokens automatically. All tokens on a connection must have access to the same repositories.
Step 2: Complete Configuration in Matia
- Under Access Tokens, click + Add and enter the token you generated. Click + Add again to enter additional tokens, if you generated more than one.
- Under Sync Repositories, choose whether to sync all repositories the token can access or only selected repositories.
- Enter an Asset Name.
- (Optional) Enter a Description.
- (Optional) Assign Tags.
- Select an Owner.
- Verify that your GitHub account is successfully connected by clicking on Test Connection.
- Click Connect.
Permissions by stream
| Stream | Classic token scope | Fine-grained token permission |
|---|---|---|
repository, repository_topic, repository_property, repo_team, repo_collaborator, stargazer | repo | Repository: Metadata |
commit | repo | Repository: Contents, Checks, Commit statuses |
pull_request | repo | Repository: Pull requests, Issues |
issue, label, milestone | repo, read:project | Repository: Issues; Organization: Projects |
project, column, card | read:project | Organization: Projects |
release | repo | Repository: Contents |
deployment | repo | Repository: Deployments |
workflow, workflow_run | repo | Repository: Actions |
security_alert | repo | Repository: Dependabot alerts |
team, team_membership | read:org | Not supported - use a classic token |
copilot_metric | read:org | Organization: GitHub Copilot Business |
copilot_metric_team | read:org | Not supported - use a classic token |
Note: The issue stream reads each issue's GitHub Projects fields, so it requires read:project (classic) or Projects read access (fine-grained) even if you don't sync the project stream.