GitHub

Integration

Connect via GitHub App for secure, scoped repository access.

GitHub integration uses a GitHub App rather than OAuth tokens. This provides better security, granular permissions, and works across organizations.

Setup Guide

Install the GitHub App

Install the Arbtr GitHub App on your organization or personal account.

Visit github.com/apps/arbtr-adr → Install → Select your organization and repository

App Permissions:

• Contents: Read (Read-Only mode) or Read & Write (Full Access)
• Pull requests: Read (Read-Only mode) or Read & Write (Full Access)
• Metadata: Read

Copy the Installation ID

After installation, you need to copy the Installation ID from GitHub.

How to find it:

Go to GitHub → Settings → Applications
Click "Installed GitHub Apps"
Find "Arbtr ADR" and click Configure
Look at the URL—the number at the end is your Installation ID

Example: github.com/settings/installations/12345678

Configure in Arbtr

Go to your team's Integrations page (Settings → Integrations) and select the GitHub tab.

Fill in the following:

Installation ID:The number from step 2 (e.g., 12345678)
Repository Owner:Your org or username (e.g., acme-corp)
Repository Name:The repo name (e.g., backend-monolith)
Branch:Target branch, usually main
ADR Directory:Where to store ADRs (e.g., docs/adr)

Choose Integration Mode

Select whether you want Read-Only or Full Access mode.

Read-Only

For Arbtr code analysis, PR search, and repo browsing.

Full Access

All of the above plus publishing decisions as ADRs.

You'll need to install the appropriate GitHub App for your chosen mode. Read-Only uses "Arbtr Auditor", Full Access uses "Arbtr Sync".

Test and Save

Click "Test Connection" to verify everything is configured correctly, then save your settings.

The test will verify that Arbtr can access your repository. If the test fails, double-check your Installation ID and ensure the GitHub App has access to the specified repository.

Publishing Decisions

Once configured with Full Access mode, you can publish concluded decisions to GitHub:

Manual Publishing

On any concluded decision, click Actions → Publish to Git. This creates a Pull Request with your ADR file. Review and merge the PR in GitHub.

Auto-Publishing

Enable "Auto-publish on conclusion" in Integrations settings. Decisions will be automatically published when you approve the comprehensive summary.

PR Policy Enforcement

With Full Access mode, you can also enable PR Policy Enforcement—automated checks that verify pull requests comply with your architecture decisions.

What It Does

• Automatically checks PRs for blocked dependencies (e.g., moment.js)
• Detects forbidden file patterns (e.g., *.js when TypeScript is required)
• Posts GitHub Check Runs with pass/fail status
• Optionally posts PR comments with violation details
• Links back to the relevant architecture decisions

Learn more about PR Policy Enforcement

Troubleshooting

'Bad credentials' or 401 error

The Installation ID is incorrect or the GitHub App has been uninstalled. Verify the Installation ID and reinstall the app if needed.

'Resource not accessible' or 403 error

The GitHub App doesn't have access to the specified repository. Go to the app's settings in GitHub and add the repository to the installation.

'Repository not found' or 404 error

Either the repository doesn't exist, or the owner/name is misspelled. Double-check the Repository Owner and Repository Name fields.

Switching repositories

To publish to a different repository, update the Repository Owner and Repository Name in your integration settings. Make sure the GitHub App is installed on the new repository.

Git Providers

GitLab Setup

Command Palette