Skip to main content

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

  1. Sign in to GitHub.
  2. Click your profile photo in the top-right corner, then click Settings.
  3. In the left sidebar, click Developer settings.
  4. Click Personal access tokens → Tokens (classic).
  5. Click Generate new token → Generate new token (classic).
  6. Enter a descriptive Note, e.g. Matia Integration.
  7. Set an Expiration for the token.
  8. Under Select scopes, check repo, read:org, and read:project.
  9. Click Generate token.
  10. Copy the generated token now - GitHub will not show it again.

Option B: Fine-grained token

  1. Sign in to GitHub.
  2. Click your profile photo in the top-right corner, then click Settings.
  3. In the left sidebar, click Developer settings.
  4. Click Personal access tokens → Fine-grained tokens, then click Generate new token.
  5. Enter a descriptive Token name, e.g. Matia Integration, and set an Expiration.
  6. Under Resource owner, select the organization you want to sync.
  7. Under Repository access, select All repositories or Only select repositories.
  8. Grant the permissions listed in the Permissions by stream table below. All of them are Read-only.
  9. Click Generate token. If your organization requires approval for fine-grained tokens, an organization owner must approve the token before Matia can use it.
  10. 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

  1. Under Access Tokens, click + Add and enter the token you generated. Click + Add again to enter additional tokens, if you generated more than one.
  2. Under Sync Repositories, choose whether to sync all repositories the token can access or only selected repositories.
  3. Enter an Asset Name.
  4. (Optional) Enter a Description.
  5. (Optional) Assign Tags.
  6. Select an Owner.
  7. Verify that your GitHub account is successfully connected by clicking on Test Connection.
  8. Click Connect.

Permissions by stream

StreamClassic token scopeFine-grained token permission
repository, repository_topic, repository_property, repo_team, repo_collaborator, stargazerrepoRepository: Metadata
commitrepoRepository: Contents, Checks, Commit statuses
pull_requestrepoRepository: Pull requests, Issues
issue, label, milestonerepo, read:projectRepository: Issues; Organization: Projects
project, column, cardread:projectOrganization: Projects
releaserepoRepository: Contents
deploymentrepoRepository: Deployments
workflow, workflow_runrepoRepository: Actions
security_alertrepoRepository: Dependabot alerts
team, team_membershipread:orgNot supported - use a classic token
copilot_metricread:orgOrganization: GitHub Copilot Business
copilot_metric_teamread:orgNot 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.