# GitHub Integration

*Semantic PR review, intent trailers, and shadow branches on GitHub.*

## Overview

Aura is designed to sit next to GitHub, not replace it. Your code, PRs, and review workflow stay exactly where they are. Aura layers on top: semantic PR review, intent metadata in commit trailers, and shadow branches that make AST-level history available to CI without polluting the mainline.

Three integration points matter:

1. **`aura pr-review`** — a command you run locally or in CI to produce a semantic diff report for any PR.
2. **GitHub Actions workflow** — runs `aura prove` and `aura pr-review` as a required check.
3. **Intent metadata in commit trailers** — every commit Aura produces carries a machine-readable `Aura-Intent:` trailer.

Optionally, Aura pushes **shadow branches** (prefixed `aura/`) that contain the AST graph, snapshots, and intent log for each branch. These let tooling reconstruct semantic state on any clone without needing access to your local `.aura/` directory.

## Setup

### 1. Install the Aura GitHub App (optional but recommended)

The Aura GitHub App posts PR review comments as rich check-run annotations. Install it from the GitHub Marketplace and grant read/write access to your repos.

If you skip the app, `aura pr-review` still works — it just writes to stdout and can be posted as a plain comment via `gh pr comment`.

### 2. Add the GitHub Actions workflow

Create `.github/workflows/aura.yml`:

```yaml
name: Aura Semantic Review

on:
  pull_request:
    branches: [main]

jobs:
  aura:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Aura needs full history for semantic diff.

      - name: Install Aura
        run: curl -fsSL https://aura.build/install.sh | sh

      - name: Fetch shadow branches
        run: git fetch origin '+refs/heads/aura/*:refs/remotes/origin/aura/*'

      - name: aura prove
        run: aura prove --base origin/${{ github.base_ref }}

      - name: aura pr-review
        run: aura pr-review --base origin/${{ github.base_ref }} --format github
        env:
          AURA_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

Commit this, open a PR, and you'll see a new check named `aura` on every future PR.

### 3. Enable branch protection

In **Settings → Branches → Branch protection rules**, add `aura` to the list of required status checks on `main`. Now a PR cannot merge if `aura prove` fails or `aura pr-review` finds unresolved violations.

## Configuration

### `.aura/github.toml`

```toml
[pr_review]
# Fail the check on these violation severities.
fail_on = ["error", "warning"]

# Post inline review comments on changed lines.
inline_comments = true

# Label PRs based on semantic analysis.
auto_label = true

[labels]
breaking_change = "breaking"
intent_mismatch = "needs-intent-review"
layer_violation = "architecture"

[shadow_branches]
# Push shadow branches on every push to the mainline.
auto_push = true
prefix = "aura/"
```

### Intent trailers

Every `aura save` (or `git commit` when the pre-commit hook runs) adds trailers to the commit message:

```
Refactor retry_logic to use exponential backoff

Aura-Intent: Switch linear backoff to exponential for rate-limit compliance
Aura-Intent-ID: itn_01HW3K9Z4X7P2Q8R
Aura-Nodes-Changed: 3
Aura-Nodes-Added: 1
Aura-Nodes-Deleted: 0
Aura-Prove-Goal: "Retries respect Retry-After header"
Aura-Prove-Result: pass
```

These are standard Git trailers (RFC-compatible). They work with `git interpret-trailers`, GitHub's commit-metadata features, and any downstream tool that parses commit messages.

## Examples

### Running PR review locally

```bash
aura pr-review --base main --format markdown > review.md
gh pr comment --body-file review.md
```

Output is a markdown report with sections for:

- **Summary.** Nodes added/modified/deleted.
- **Intent mismatches.** Where the stated intent doesn't match the AST diff.
- **Architectural drift.** Layer violations, circular deps, new cross-module coupling.
- **Security findings.** Hardcoded secrets, unsafe deserialization, SSRF patterns.
- **Accidental deletions.** Functions removed with no intent covering deletion.

### The shadow branch model

When `auto_push = true`, Aura maintains a companion branch for every real branch:

| Real branch | Shadow branch | Contents |
|-------------|---------------|----------|
| `main` | `aura/main` | AST snapshots, intent log for main |
| `feat/login` | `aura/feat/login` | AST + intents for the feature branch |
| `release/v1.2` | `aura/release/v1.2` | AST + intents for the release branch |

Shadow branches never contain source code — only `.aura/` artifacts. They are tiny (usually <5 MB even for large repos) and can be aggressively garbage-collected. CI fetches them to reconstruct semantic state without needing a fresh `aura init`.

To push shadow branches manually:

```bash
aura shadow push origin
```

To disable them entirely:

```toml
[shadow_branches]
auto_push = false
```

### Gating merges on `aura prove`

In the workflow above, `aura prove` runs with no arguments — it re-verifies every goal logged during the branch's lifetime. You can also gate on a specific goal:

```yaml
- run: aura prove "OAuth login round-trip works end-to-end"
```

Exit codes:

| Code | Meaning |
|------|---------|
| `0` | All goals proved. |
| `1` | One or more goals failed. |
| `2` | No goals logged (treated as pass by default; configurable). |
| `3` | Engine error (e.g. missing shadow branch). |

See [CI/CD integration](/ci-cd-integration) for the full table.

### Intent in squash-merges

GitHub's "Squash and merge" collapses trailers. Aura detects this and rewrites the final squash commit message to preserve an `Aura-Intent-Squashed:` trailer summarizing all squashed intents. You don't need to do anything — but if you use a custom merge queue, make sure it invokes `aura rewrite-trailers --squash` before pushing.

## Troubleshooting

**`aura pr-review` fails with `no shadow branch`.** The workflow didn't fetch shadow branches, or `auto_push` was never enabled. Run `aura shadow push origin` once on a machine that has the full `.aura/` directory.

**Inline comments not posting.** The `GITHUB_TOKEN` must have `pull-requests: write`. Add this to your workflow:

```yaml
permissions:
  contents: read
  pull-requests: write
  checks: write
```

**Shadow branch size growing.** Run `aura shadow gc` monthly. It prunes snapshots older than the retention window (default 90 days).

**Trailers missing from commits.** The pre-commit hook didn't run. Check `.git/hooks/pre-commit` and re-install with `aura hooks install`. See [pre-commit hook](/pre-commit-hook-explained).

**Aura App posts duplicate comments.** You have both the app and the workflow posting reviews. Pick one: either disable `inline_comments` in `.aura/github.toml`, or uninstall the app.

## PR Labels Aura Can Manage

With `auto_label = true`, Aura applies labels based on the semantic diff. The default set:

- `aura:breaking` — public API signature change.
- `aura:new-feature` — new top-level module or entry point.
- `aura:refactor-only` — nodes renamed or restructured, no behavior change.
- `aura:intent-review` — intent doesn't match AST diff.
- `aura:security` — security finding raised by review.
- `aura:architecture` — layer violation detected.

These are orthogonal to whatever labels your team manages manually. A PR can carry both `needs-review` (human) and `aura:refactor-only` (machine). Filter and triage on either.

## Review Comment Anatomy

A typical `aura pr-review` inline comment looks like this:

```markdown
**Aura: accidental deletion** (severity: error)

Function `billing::Invoice::apply_tax` was removed.
Stated intent: "Clean up unused helpers in billing module."
AST diff: no evidence `apply_tax` was unused — still called from
`billing::Invoice::finalize` (line 204) and 3 tests.

Suggested fix: revert the deletion, or extend the intent to explain
why `apply_tax` is safe to remove.
```

Each comment carries:

- **Severity.** `error`, `warning`, `info`. Maps to check-run conclusion.
- **Category.** `accidental_deletion`, `intent_mismatch`, `layer_violation`, `security_finding`, `dead_code`.
- **Evidence.** A machine-generated paragraph explaining why Aura flagged the node.
- **Suggested fix.** Either a code suggestion block (for simple cases) or guidance for a human reviewer.

Reviewers can dismiss individual findings with `!aura-dismiss <fingerprint>` in a reply comment. Dismissals persist across re-runs of the check on the same PR.

## Working with Merge Queues

GitHub's merge queue reorders PRs and re-runs required checks on each proposed merge commit. Aura works with the queue out of the box: the workflow above runs on the queue's synthetic commits because the trigger includes queue-generated pull events. A few specifics to know:

- **Intent trailers survive.** The queue's rebase-and-merge mode preserves per-commit trailers. Squash mode collapses them; Aura rewrites the final commit message with an `Aura-Intent-Squashed:` aggregator.
- **Shadow branches lag one commit.** The queue produces a new SHA at merge time that is not in any dev branch. The shadow branch catches up in the next push to `main`.
- **Re-proving on queue commits.** `aura prove` re-runs on the queue commit, not the original PR HEAD. If a goal depended on a commit that got rebased away, it is surfaced as a violation, not silently dropped.

## Using `gh` CLI Idiomatically

For scripts and local tooling, `aura pr-review` pairs naturally with `gh`:

```bash
# Post review as a PR comment
aura pr-review --base main --format markdown > /tmp/review.md
gh pr comment --body-file /tmp/review.md

# Fail a workflow based on review severity
aura pr-review --base main --fail-on error
```

The combination of `gh pr list --search` and `aura pr-review --pr <number>` makes it easy to batch-audit many PRs at once.

## GitHub Enterprise Server

On GitHub Enterprise Server (3.x+), set `AURA_GITHUB_URL` to your instance URL. Everything else works identically:

```bash
export AURA_GITHUB_URL=https://github.internal.example.com
export AURA_GITHUB_TOKEN=ghp_...
aura pr-review --base main --format github
```

If your GHES uses a private CA, set `AURA_CA_BUNDLE` as with the other integrations.

## See Also

- [GitLab integration](/gitlab-integration) — the equivalent for GitLab.
- [CI/CD integration](/ci-cd-integration) — running Aura in any CI.
- [Semantic diff](/semantic-diff) — what `aura pr-review` actually computes.
- [Linear / Jira integration](/linear-jira-integration) — tying intents to tickets.