Skip to main content

Connecting GitHub

To sync Terraform templates from your repository, you need to connect a GitHub repository to Amnify using a personal access token.

info

GitHub integrations are used only by the Deploy module for template synchronization. They do not participate in security scanning.

Prerequisites​

Before you begin, make sure you have:

  • A GitHub account with access to the repository containing your Terraform templates
  • The repository follows the Amnify template structure
  • The following values ready:
    • Repository — in owner/repo format (e.g., my-org/infra-templates)
    • Access Token — a GitHub personal access token with read access to the repository

Choosing a Token Type​

GitHub offers two types of personal access tokens:

TypePrefixBest for
Fine-grained (recommended)github_pat_...Scoping access to a single repository with minimal permissions
Classicghp_...Quick setup when you're comfortable granting broader access

We recommend fine-grained tokens because they let you restrict access to the specific repository that contains your templates — nothing else in your GitHub account is exposed.

Step 1: Create the Token​

  1. Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. Click Generate new token
  3. Fill in:
    • Token name — e.g., Amnify Template Sync
    • Expiration — choose an appropriate expiration (e.g., 90 days, or custom)
    • Resource owner — select the organization or account that owns the repository
  4. Under Repository access, select Only select repositories and pick the repository that contains your templates
  5. Under Permissions → Repository permissions, grant:
    • Contents → Read-only
    • Metadata → Read-only (automatically selected)
  6. Click Generate token
  7. Copy the token immediately — it starts with github_pat_ and won't be shown again
tip

Fine-grained tokens can require organization approval. If your organization has an approval policy, an organization admin will need to approve the token before it becomes active. Check with your GitHub organization admin if your token shows a "pending" status.

Step 2: Add the Integration in Amnify​

  1. Navigate to Integrations and click Create integration
  2. Select GitHub as the provider
  3. Fill in:
    • Display Name (optional) — a friendly label (e.g., "Infra Templates Repo")
    • Repository — in owner/repo format (e.g., my-org/infra-templates)
    • Branch (optional) — the branch to sync from; defaults to main if not provided
    • Access Token — paste the github_pat_... token
  4. Click Create

Method 2: Classic Token​

Use this if fine-grained tokens are not available in your organization or you prefer a simpler setup.

Step 1: Create the Token​

  1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Click Generate new token (classic)
  3. Fill in:
    • Note — e.g., Amnify Template Sync
    • Expiration — choose an appropriate expiration
  4. Under Select scopes, check:
    • repo (Full control of private repositories) — required for reading private repository contents
  5. Click Generate token
  6. Copy the token immediately — it starts with ghp_ and won't be shown again
caution

Classic tokens grant access to all repositories your account can access, not just one. If your account has access to many repositories, prefer a fine-grained token to limit the blast radius.

Step 2: Add the Integration in Amnify​

Follow the same steps as Method 1, Step 2 above.

What Happens Next​

Once connected, you can:

  • Navigate to Deploy → Templates and click Sync Templates to import templates from your repository
  • Browse and use synced templates when creating Deployments
  • Add or modify templates by pushing changes to your repository and syncing again

Rotating Tokens​

When your token expires, Amnify will no longer be able to sync templates. To rotate:

  1. Generate a new token in GitHub following the steps above
  2. Delete the existing GitHub integration in Amnify
  3. Create a new integration with the new token

Troubleshooting​

IssueCauseSolution
Sync fails with 401Token is invalid or expiredGenerate a new token and recreate the integration
Sync fails with 404Repository not found or token lacks accessVerify the owner/repo format is correct and the token has access to that repository
No templates found after syncRepository doesn't follow the expected structureEnsure templates are in a templates/ directory — see repository structure
Fine-grained token shows "pending"Organization requires admin approvalAsk your GitHub organization admin to approve the token
Sync returns outdated templatesWrong branch configuredVerify the branch field matches where your templates live (defaults to main)