Creating the GitHub App¶

This guide walks through creating a GitHub App for the versionconductor[bot] identity.

Why Use a GitHub App?¶

Feature	GITHUB_TOKEN	GitHub App
Identity	`github-actions[bot]`	`versionconductor[bot]`
Audit trail	Generic	Clear bot identity
Token lifetime	Job duration	1 hour (renewable)
Permissions	Repository-scoped	Fine-grained per installation
Cross-repo	No	Yes (within installation)

Step 1: Create the App¶

Navigate to your organization's app settings:

https://github.com/organizations/YOUR_ORG/settings/apps/new

Or: GitHub → Your Org → Settings → Developer settings → GitHub Apps → New GitHub App

Basic Information¶

Field	Value
GitHub App name	`versionconductor`
Description	Automated dependency PR management
Homepage URL	`https://github.com/YOUR_ORG/versionconductor`

Webhook¶

Uncheck Active - webhooks are not needed for this use case.

Permissions¶

Configure these Repository permissions:

Permission	Access	Purpose
Contents	Read	Read go.mod/go.sum files
Metadata	Read	Access repository metadata
Pull requests	Read and write	Approve and merge PRs
Checks	Read	Verify CI status
Commit statuses	Read	Check commit statuses

Leave all other permissions as "No access".

Installation Scope¶

Select: Only on this account

This restricts the app to your organization only.

Step 2: Note the App ID¶

After clicking "Create GitHub App", you'll see the app settings page.

Note the App ID displayed near the top - you'll need this for the workflow.

App ID: 123456

Step 3: Generate Private Key¶

Scroll down to the Private keys section
Click Generate a private key
A .pem file will download automatically
Store this file securely - it cannot be recovered if lost

Private Key Security

The private key grants full access as the app. Store it securely and never commit it to version control.

Step 4: Install the App¶

In the app settings, click Install App in the left sidebar
Select your organization
Choose installation scope:
All repositories - recommended for org-wide dependency management
Only select repositories - for limited rollout
Click Install

Step 5: Add Secrets¶

Add the App ID and private key as secrets for your workflows.

Option A: Web UI¶

Go to your organization's secrets page:

https://github.com/organizations/YOUR_ORG/settings/secrets/actions

Click New organization secret
Name: VERSIONCONDUCTOR_APP_ID, Value: your App ID (e.g., 123456)
Visibility: All repositories (or select specific repos)
Click Add secret
Repeat for VERSIONCONDUCTOR_PRIVATE_KEY (paste full .pem file contents)

Option B: GitHub CLI¶

Organization-Level Secrets (Recommended)

Makes secrets available to all repositories in the organization:

# Set App ID
gh secret set VERSIONCONDUCTOR_APP_ID \
  --body "123456" \
  --org YOUR_ORG \
  --visibility all

# Set private key from file
gh secret set VERSIONCONDUCTOR_PRIVATE_KEY \
  --org YOUR_ORG \
  --visibility all \
  < /path/to/versionconductor.pem

Repository-Level Secrets

For individual repositories:

# Set App ID
gh secret set VERSIONCONDUCTOR_APP_ID \
  --body "123456" \
  --repo YOUR_ORG/your-repo

# Set private key from file
gh secret set VERSIONCONDUCTOR_PRIVATE_KEY \
  --repo YOUR_ORG/your-repo \
  < /path/to/versionconductor.pem

Step 6: Configure Workflow¶

Update your workflow to use the GitHub App credentials:

jobs:
  auto-merge:
    uses: plexusone/.github/.github/workflows/go-dependency-automerge.yaml@main
    with:
      profile: 'quarantine'
      min-age-days: 5
    secrets:
      app-id: ${{ secrets.VERSIONCONDUCTOR_APP_ID }}
      app-private-key: ${{ secrets.VERSIONCONDUCTOR_PRIVATE_KEY }}

Step 7: Verify Setup¶

Trigger a test run to verify the app is working:

gh workflow run go-dependency-automerge.yaml \
  --repo YOUR_ORG/your-repo \
  -f dry-run=true

Check the workflow logs. You should see:

Using GitHub App token (versionconductor[bot])

PR approvals will now show as coming from versionconductor[bot].

Troubleshooting¶

"Resource not accessible by integration"¶

The app doesn't have the required permissions. Check:

App has "Pull requests: Read and write" permission
App is installed on the repository
Secrets are correctly configured

"Could not create installation token"¶

The private key or app ID is incorrect. Verify:

App ID matches the one shown in app settings
Private key is the complete .pem file contents
No extra whitespace in secrets

App not appearing in PR approvals¶

The workflow may be falling back to GITHUB_TOKEN. Check:

Both app-id and app-private-key secrets are set
Secrets are available to the workflow (check visibility settings)
Workflow logs show "Using GitHub App token"

Rotating the Private Key¶

To rotate the private key:

Go to app settings → Private keys
Click Generate a private key (creates new key)
Update the VERSIONCONDUCTOR_PRIVATE_KEY secret
Verify workflows still work
Delete the old key from app settings

Revoking Access¶

To revoke the app's access to a repository:

Go to app settings → Install App
Click the gear icon next to your organization
Under "Repository access", deselect the repository
Click Save

To completely uninstall:

Go to organization settings → Installed GitHub Apps
Click Configure next to versionconductor
Click Uninstall at the bottom

Next Steps¶

Setup Guide - Configure the workflow in your repositories
Examples - Common configuration patterns