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:

aura pr-review — a command you run locally or in CI to produce a semantic diff report for any PR.
GitHub Actions workflow — runs aura prove and aura pr-review as a required check.
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:

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`

[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

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:

aura shadow push origin

To disable them entirely:

[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:

- 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 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:

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.

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:

**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:

# 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:

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.