GitHub

GitHub integration allows agents to interact with your GitHub repositories during task execution. Agents can browse repositories, read files, create issues, open pull requests, and more.

Errand supports two authentication modes — choose the one that best fits your needs.

Authentication modes

Mode	Best for	Key benefit
Personal Access Token (PAT)	Individual users	Simple setup
GitHub App	Teams and organizations	Fine-grained permissions, audit trail

---

Option A: Personal Access Token (PAT)

Use a dedicated account

Rather than generating a token from your own GitHub account, consider creating a dedicated machine user account (e.g. “errand-bot”) and generating the token from there. This lets you control exactly which repositories and permissions Errand has access to, without exposing your personal account’s full access.

Step 1: Create a fine-grained token

1. Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Click Generate new token
3. Configure:
   • Token name: e.g. “Errand”
   • Expiration: choose an appropriate duration
   • Repository access: select the repositories you want agents to access
   • Permissions: grant the repository permissions your workflows need (e.g. Contents read/write, Issues read/write, Pull requests read/write)
4. Click Generate token and copy the value immediately

Step 2: Enter the token in Errand

1. Open the Errand UI and go to Settings > Integrations
2. Find the GitHub card and click it
3. Select Personal Access Token as the authentication mode
4. Paste your token
5. Click Test & Save — Errand will verify the token against the GitHub API

---

Option B: GitHub App

GitHub Apps provide more granular control over permissions and work well for teams.

Step 1: Create a GitHub App

1. Go to github.com/settings/apps (or your organization’s settings)
2. Click New GitHub App
3. Configure:
   • App name: e.g. “Errand”
   • Homepage URL: your Errand instance URL
   • Webhook: uncheck Active (Errand doesn’t need webhook events from the app)
4. Under Permissions, grant the repository permissions your workflows need
5. Click Create GitHub App

Step 2: Generate a private key

1. On the app’s settings page, scroll to Private keys
2. Click Generate a private key
3. A .pem file will download — keep this safe

Step 3: Install the app

1. Go to your app’s settings page and click Install App in the left sidebar
2. Choose the account or organization to install it on
3. Select which repositories the app can access
4. Click Install
5. Note the Installation ID from the URL after installation (the number at the end of the URL)

Step 4: Enter credentials in Errand

1. Open the Errand UI and go to Settings > Integrations
2. Find the GitHub card and click it
3. Select GitHub App as the authentication mode
4. Enter:
   • App ID — found on the app’s settings page (General > About)
   • Private Key — paste the contents of the .pem file
   • Installation ID — from Step 3
5. Click Test & Save — Errand will verify the credentials

How it works

• Credentials are encrypted at rest using your Errand credential encryption key
• The agent authenticates with GitHub during task execution using the stored credentials
• For GitHub Apps, Errand generates short-lived installation tokens automatically

Troubleshooting

Issue	Solution
”Bad credentials” error	Your token may have expired — regenerate it in GitHub and update it in Errand
”Insufficient permissions” error	Check that your token or GitHub App has the required permission scopes for the operation
GitHub App not working	Verify the app is installed on the target repositories and the Installation ID is correct
Token expired	Fine-grained tokens have an expiry date — create a new one and update it in Errand