GitHub source and pull requests

How GitHub works with AAI

When you connect GitHub to a domain, AAI can import supported source files from an authorised repository into Project Source.

AAI records the repository, branch, commit, file path and checksum associated with repository-sourced versions. This provenance allows Developer Studio to establish exactly which source version a repair was based on.

GitHub is the source of truth

If you use the GitHub remediation workflow, source files that AAI sends back through GitHub must originate from a connected GitHub repository.

AAI does not guess that an uploaded file belongs to a repository simply because a file with the same name or path exists there.

• Repository-sourced files retain their exact GitHub provenance.
• Workbench repairs remain linked to the source version on which they were based.
• Before a GitHub repair can proceed, AAI checks the current repository source against the version used for the repair.
• Unrelated repository changes do not invalidate a repair when the affected source file itself is unchanged.

The GitHub remediation journey

• Connect an authorised GitHub repository to the domain.
• Sync repository source into Project Source.
• Create or refresh a Workbench using the repository-sourced files.
• Review the accessibility problem and prepare the remediation.
• Review and apply the approved repair to the protected AAI Workbench copy.
• AAI verifies that the relevant GitHub source has not changed since the repair was prepared.
• The repaired change can then proceed through the GitHub pull-request workflow.
• Your development team reviews and manages the resulting change using its normal source-control process.
• After deployed source is synchronised back into AAI, accessibility retesting can verify the outcome.

Files uploaded directly to AAI

A file uploaded directly to AAI remains an uploaded Project Source file. Connecting GitHub later does not rewrite that history or automatically turn the uploaded version into repository source.

Because an uploaded file has no verified GitHub repository, branch, commit or source path, AAI will not send a repair based on that uploaded version into GitHub.

• Add or commit the file to the appropriate connected GitHub repository.
• Return to AAI and sync Project Source from GitHub.
• Use the repository-sourced version of the file in the Workbench.
• Create or refresh the remediation against that repository-sourced version.
• Run the GitHub readiness check again.

If the GitHub source has changed

AAI protects against overwriting newer development work. Before a repair proceeds through GitHub, AAI compares the current affected source file with the exact source version used to prepare the repair.

If that file has changed, been removed or can no longer be identified safely, AAI stops the GitHub workflow.

• Sync Project Source again.
• Review the newer repository source.
• Refresh or recreate the Workbench repair as appropriate.
• Review the proposed change again before attempting the GitHub workflow.

What AAI will not do

• AAI does not act as a general-purpose IDE or source-code editor.
• AAI does not decide where a manually uploaded file belongs in a repository.
• AAI does not silently map uploaded files to similarly named GitHub files.
• AAI does not rewrite historical source provenance.
• AAI does not silently overwrite newer source changes made by another developer.
• AAI does not silently refresh a Workbench when its repository changes.
• AAI does not treat a successful remediation proposal as proof that the resulting website is accessible; the affected accessibility requirement still needs appropriate retesting and verification.

More than one repository

A domain may legitimately use more than one connected repository, for example separate frontend and backend repositories.

The important rule is not that a domain must have only one repository. The rule is that each file participating in the GitHub remediation workflow must have traceable provenance from the repository that owns that source.