GitHub Integration

Connect GitHub to capture decisions from pull requests, issues, and discussions.

Features

• PR capture — Capture decisions from PR descriptions and comments
• Issue capture — Track decisions in GitHub Issues
• ADR detection — Discover Architecture Decision Records
• Evidence linking — Link decisions to PRs, issues, and commits

Setup (Cloud)

1. Go to Settings → Integrations in Align
2. Click Connect GitHub
3. Authorize Align (GitHub App)
4. Select repositories to include

Capturing Decisions

From Pull Requests

Add a comment with the decision:

@align-bot We decided to use the Repository pattern here
instead of direct database access for better testability.

Or include in the PR description:

## Decision

Using GraphQL for the new API because:
- Flexible queries for mobile clients
- Strong typing with codegen
- Better developer experience

From Issues

Comment on any issue:

@align-bot Decided to postpone this to Q3 due to resource constraints.

Discover Mode

Discover scans your GitHub repos for:

• ADRs — Files matching adr-*.md, docs/decisions/*.md
• RFCs — Request for Comments documents
• Decision comments — PR/Issue comments with decision language
• Architecture docs — Files in docs/architecture/

Running Discover

1. Go to Discover in Align
2. Select GitHub as the source
3. Choose repositories
4. Review suggested decisions
5. Import the relevant ones

Best Practices

1. Use ADRs — Architecture Decision Records are automatically detected
2. Document in PRs — Include decision rationale in PR descriptions
3. Link issues — Reference related issues in decisions
4. Tag appropriately — Use labels like decision or adr

Permissions

Align's GitHub App requires:

Permission	Purpose
Contents: Read	Read ADRs and docs
Issues: Read & Write	Read issues, add comments
Pull requests: Read & Write	Read PRs, add comments
Metadata: Read	Repository information

Evidence

When a decision is captured from GitHub, evidence includes:

• Link to the PR or issue
• Repository name
• PR/Issue number and title
• Author information

ADR Template

Align recognizes standard ADR formats:

# ADR-001: Use PostgreSQL for User Data

## Status
Accepted

## Context
We need a database for user data that supports...

## Decision
We will use PostgreSQL because...

## Consequences
- Positive: Strong consistency...
- Negative: More operational overhead...

Troubleshooting

Align doesn't respond

• Ensure the GitHub App is installed on the repo
• Check that the repo is selected in Align settings

Missing ADRs

• Verify ADR files match expected patterns
• Check file permissions

Self-Hosted Setup

See Self-Host OAuth Apps for registering your own GitHub App.