GitHub Integration

GitHub does two jobs in Align, and they are easy to mix up.

Validation. Every pull request is checked against the decisions already in your graph. Align posts an Align Report comment and an Align Decision Check status on the PR. This is the last-mile gate: decisions are captured where they get made, and GitHub is where code meets them.

Capture. Three paths, and only two of them are things you trigger. A /align comment on a PR or issue records a decision, and Discover scans your repos for ADRs and RFCs. The third runs on its own: when a pull request merges, Align captures it as a decision. That is the default (auto_capture_merged), and it is the highest-volume path by a wide margin - turn it off per repository if you would rather it did not.

Align still does not read your commit history to work out what you decided, because a commit shows what was built, never why, and never what you rejected. A merged pull request is a different artefact: it carries a description, a review, and an outcome.

For how this sits against the other tools, see Capture sources vs. the validation gate.

Features

Validation:

• Align Report - a PR comment carrying the verdict and the decisions the change touches
• Align Decision Check - a PR status you can make a required check
• /align check - re-run the check on demand

Capture:

• Merged-PR capture - a merged pull request is captured as a decision, automatically. On by default
• 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

Validation: the Align Report and the Align Decision Check

When a pull request opens or gets pushed to, Align compares the change against the decisions already in your graph and reports back in two places.

The Align Report

A PR comment titled Align Report, with the verdict, the decisions the change relates to, and why each one matched:

## Align Report

**Aligned** · relates to 5 tracked decisions

### Related Decisions

| Decision | Status | Notes |
|----------|--------|-------|
| [Enforce plain hyphens in user-facing copy](https://app.align.tech/decisions/...) | Aligned | The PR description calls out "zero em-dashes", and the diff contains none. |

No conflicts found.

The comment is rewritten in place on each push, so a pull request carries one report rather than one per commit. Comment /align check to re-run it yourself.

The Align Decision Check

A GitHub check run named Align Decision Check. Make it a required status if you want a conflict to block the merge.

Result	When you get it
Pass	No critical conflict, and the change lines up with the decisions it touches
Neutral	No decision relates to the change, or there are non-critical points worth a look
Fail	At least one critical conflict

The check names what it found, so "2 conflicts to review" and "No related decisions found" are both neutral results and they mean different things.

A check that reports success when it never ran is worse than no check, so Align does not do that. If the analysis could not complete, you get a neutral result that says so on its face rather than a green tick.

Two ways to run it

The check is available either through the hosted GitHub App or as a standalone GitHub Action, and they suit different situations.

	Align GitHub App	aligndottech/decision-check
Install	GitHub App install, needs an org admin	A workflow file and two secrets
Scope	Decision capture, PR linking, and the check	The check only
Runs on	Align's infrastructure	Your CI runner
Threshold	Fails on a critical conflict	Yours to set, via fail-on: critical, any or none

Use the App if you want capture and validation together. Use the Action if you only want the gate, or if you would rather the call came from your own runner.

Capturing Decisions

From Pull Requests

Comment /align on a pull request and Align analyzes the description and discussion to capture the decision:

/align

Or include the rationale directly in the PR description and run /align:

## Decision

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

From Issues

Comment /align on any issue to capture a decision from the discussion:

/align

Align reads the issue and thread, then synthesizes the decision, rationale and participants. Run /align check instead to test a proposed change against existing decisions before you commit to it.

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 the Align Report comment
Checks: Read & Write	Create the Align Decision Check status
Metadata: Read	Repository information

Without Checks: Read & Write the Align Report comment still posts and the Align Decision Check never appears, which looks like the feature working rather than a permission gap. If you see the comment but no status, grant the permission and re-authorise the installation.

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

The Align Report posts but there is no Align Decision Check

The installation is missing Checks: Read & Write. See Permissions.

Self-Hosted Setup

Self-hosted Align uses Align's centrally-managed GitHub App by default - see Connector Authentication, which also covers what to do if your security policy requires your own app.