Connecting a GitHub repository

Overview

The repository integration links your GitHub codebase to your AAC project’s compliance record. Once connected:

• Every push to the default branch and every opened or updated pull request triggers a scan
• The scanner reads .aac/repo.yml from the exact commit, then creates or updates ImplementationItem, SourceCodeReference, and BuildConfiguration artefacts in your project
• Traceability relationships are created automatically — ImplementationItems link to the requirements they satisfy; SourceCodeReferences link to the ImplementationItems they implement
• Validation and release-gate results are posted back to GitHub as check runs on the PR
• When a baseline is generated, the exact commit SHA for every active connector is recorded — the audit trail includes precisely what code was released

Prerequisites

• A running AAC deployment (see Deployment guide)
• Admin role in the AAC project you want to connect
• A GitHub account with permission to create and install GitHub Apps on the target repository

Create the GitHub App

Register a new GitHub App under your GitHub account or organisation:

1. Go to Settings → Developer settings → GitHub Apps → New GitHub App
2. Set a name and homepage URL (your AAC deployment URL works)
3. Set the webhook URL to: https://<your-deployment>/api/v1/integrations/github/webhook/<connector_id> (you will get the connector_id after step 4 — you can update this URL then)
4. Set a webhook secret (keep this for the connector config below)

Required repository permissions:

Subscribe to events: push, pull_request

5. Save the App and note the App ID
6. Generate a private key (PEM file) — download and keep it securely

Install the App on the target repository: App page → Install App → select the repository. Note the Installation ID from the URL after install (https://github.com/settings/installations/<installation_id>).

Configure the connector

In the AAC web console, go to Project → Settings → Repository Connectors → Add connector.

Secrets are encrypted at rest and never returned by the API after submission — you cannot retrieve them; only replace them.

Click Test connection to verify the App can reach the repository before saving.

Add .aac/repo.yml to your repository

Commit a mapping file to your repository at the path .aac/repo.yml. This file tells the scanner what each piece of code implements.

Minimum structure:

version: 1

implementation_items:
  - id: brake_monitor
    path: src/brake/monitor.py
    language: python
    satisfies:
      - SSR-001          # requirement ID in your AAC project

source_references:
  - path: src/brake/monitor.py
    lines: 10-80
    implements:
      - brake_monitor

build_configurations:
  - id: ci-main
    workflow: github-actions
    build_ref: main

The satisfies values must match requirement IDs that already exist in your AAC project. The scanner creates the traceability link but does not create the requirement itself.

The scanner rejects the file if the YAML root is not an object, the version is unsupported, required fields are missing, or a referenced path does not exist in the scanned commit tree.

Trigger a manual scan

After saving the connector, trigger the first scan manually:

• Web console: Project → Repository Connectors → select connector → Scan now
• API: POST /api/v1/projects/{project_id}/repo-connectors/{connector_id}/scan

Check scan status:

GET /api/v1/projects/{project_id}/repo-connectors/{connector_id}/scans/{scan_id}

A completed scan creates or updates artefacts in your project. Check the project artefact list to see ImplementationItems and SourceCodeReferences.

Webhook setup

Update the webhook URL in your GitHub App settings to:

https://<your-deployment>/api/v1/integrations/github/webhook/<connector_id>

From this point, every push to the default branch and every opened or updated PR triggers a scan automatically. The webhook endpoint verifies the X-Hub-Signature-256 header before processing — invalid signatures are rejected with HTTP 401.

What gets created

Each scan creates or updates the following artefact types:

All repository-sourced artefacts include: connector ID, repository URL, file path, commit SHA, and branch. This metadata is what gates baseline generation — the tool requires that implementation and source-code references have connector and commit evidence before a release baseline can be created.