Skip to content

GitHub App Authentication

For enterprises that prefer GitHub Apps over personal access tokens (PATs).

Benefits

  • No user-tied credentials - App identity is separate from individual users
  • Fine-grained permissions - Request only the permissions you need
  • Better audit trails - All actions attributed to the app
  • Verified commits - Commits signed by GitHub and show "Verified" badge
  • Multiple installations - One GitHub App can be installed across multiple accounts

Setup

1. Create a GitHub App

  1. Go to your organization's settings > Developer settings > GitHub Apps
  2. Click "New GitHub App"
  3. Configure permissions:
  4. Repository permissions:
    • Repository creation: Read and write (required to create, migrate and fork repos; Administration does not let the App create repos, see Repo Lifecycle)
    • Administration: Read and write (required to archive and fork repos and for repo lifecycle settings, see Repo Lifecycle; also required to create, update and delete environments and their branch policies, and to manage Actions settings)
    • Actions: Read (required to list environments and their branch policies, see Environments; also required to read the Actions cache storage limit for settings.actions)
    • Environments: Read and write (required for environment secrets, see Environments)
    • Contents: Read and write
    • Pull requests: Read and write
    • Workflows: Read and write (required if syncing .github/workflows/ files)
    • Variables: Read and write (required for settings.variables)
  5. Where can this GitHub App be installed? Any account
  6. Create the app and note the Client ID (starts with Iv23)
  7. Generate a private key (downloads a .pem file)

2. Install the App

  1. Go to your app's settings > Install App
  2. Install the app in each organization where xfg will sync configs
  3. Select the repositories the app can access (all or specific repos). Every repository in your xfg config must be one the installation can access.

3. Store Credentials

In your GitHub repository:

  • Variables: CLIENT_ID (the GitHub App Client ID, starts with Iv23)
  • Secrets: APP_PRIVATE_KEY (contents of the .pem file)

4. Update Your Workflow

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: anthony-spruyt/xfg@v9 # x-release-please-major
        with:
          config: sync-config.yaml
          github-client-id: ${{ vars.CLIENT_ID }}
          github-app-private-key: ${{ secrets.APP_PRIVATE_KEY }}

This approach:

  • Discovers all installations of your GitHub App
  • Generates short-lived tokens (1 hour) per-installation
  • Caches tokens to minimize API calls
  • Skips repositories whose owner has no installation of the app (No GitHub App installation found for <owner>)

xfg skips a repository only when its owner has no installation. A repository the installation cannot access, for example one left out of a "selected repositories" installation, fails.

The same inputs work with command: secrets-sync. Grant the app Secrets: Read and write for repo secrets, Environments: Read and write for environment secrets, and Actions: Read to list a repo's environments. Unlike sync, secrets sync fails (rather than skips) repos whose owner has no installation.

How It Works

When GitHub App credentials are provided, xfg:

  1. Generates a JWT using your Client ID and private key
  2. Discovers installations by calling GitHub's API to list all installations
  3. Generates installation tokens per-installation (tokens are cached for 45 minutes)
  4. Uses GraphQL API for commits with the installation token, creating verified commits

This uses GitHub's createCommitOnBranch mutation instead of git commands, which:

  • Creates commits that are automatically signed by GitHub
  • Shows the "Verified" badge on commits
  • Attributes commits to your GitHub App (e.g., my-app[bot])

Environment Variables

Variable Auth Type Description
XFG_GITHUB_CLIENT_ID GitHub App GitHub App Client ID for installation token generation
XFG_GITHUB_APP_PRIVATE_KEY GitHub App Private key (PEM) for JWT signing
GH_TOKEN PAT Personal Access Token for GitHub API
XFG_ALLOWED_GITHUB_HOSTS Both GitHub Enterprise Server hosts trusted with credentials

xfg sends App JWTs, installation tokens and GH_TOKEN only to github.com, unless a host is listed in XFG_ALLOWED_GITHUB_HOSTS (comma- or space-separated hostnames). Repos on any other GitHub host fail. See GitHub Enterprise Server.

When XFG_GITHUB_CLIENT_ID and XFG_GITHUB_APP_PRIVATE_KEY are set, xfg uses GitHub App authentication with automatic per-installation token generation. A repository whose owner has no installation of the app is skipped. A repository the installation cannot access fails.

Note: You can also get verified commits with PATs by configuring GPG signing. GitHub App authentication is an alternative that doesn't require GPG key management.

Limitations

  1. Commit author - Commits appear as the GitHub App, not a custom user
  2. File size - A commit whose added and modified files total more than 50MB after base64 encoding (about 37MB of raw content) can't go through the GraphQL API; use the PAT flow instead
  3. GHE compatibility - Requires GitHub Enterprise Server 3.6+
  4. Atomic commits - All file changes in a single commit (executable file mode changes use a follow-up commit)
  5. Forks - GitHub only lets an App fork a repo when it is installed on the target account with access to all its repositories, and on the upstream account with access to the upstream repo. See Repo Lifecycle.

Troubleshooting

"HTTP 403: Rate Limit Exceeded" when creating a repo

GitHub can report a missing App permission this way. xfg stops at once and names the permissions it needs:

  • Create and migrate: Repository creation: Read and write
  • Fork: Repository creation: Read and write, Administration: Read and write, and Contents: Read, with the App installed as described in Limitations

After you change the App's permissions, approve them on the installation.

"Resource not accessible by integration"

The app lacks required permissions. Check that:

  • Contents permission is set to "Read and write"
  • Pull requests permission is set to "Read and write"
  • Workflows permission is set to "Read and write" (if syncing .github/workflows/ files)
  • The app is installed on the target repository

Note: The Workflows permission is required when syncing workflow files (.github/workflows/) because the createCommitOnBranch GraphQL mutation enforces this separately from the Contents permission. Without it, git push may succeed but the GraphQL commit will fail.

Commits not showing as verified

Ensure you're using GitHub App authentication (github-client-id and github-app-private-key inputs). Only installation tokens from GitHub Apps trigger the GraphQL verified commit flow.

Payload too large

The added and modified files in one commit cannot exceed 50MB combined after base64 encoding (about 37MB of raw content) when committed via the GraphQL API. Use GH_TOKEN (PAT authentication) for repositories with large files.