GitHub Integration

Align connects to GitHub through a GitHub App that Align registers and runs. Your workspace connects its own GitHub account or organisation to that app. You never enter an app ID, a private key or a client secret.

Once an account is connected, Align links commits and pull requests to entries, credits them to the right people, records CI results, and can move entries forward when work is merged and deployed. For how integrations work in general, see Integrations.

Connecting a GitHub account

You need the Admin role in the Align workspace, and permission to install GitHub Apps on the GitHub account or organisation.

1. Go to Settings → Integrations. Under Developer Tooling, turn on the GitHub switch.
2. Click Configure on the GitHub row. The GitHub App Configuration panel opens.
3. Click Install to GitHub Org. GitHub opens.
4. On GitHub, choose the account or organisation and the repositories the app may access, and confirm.
5. GitHub sends you back to Align. The account appears under Connected Organizations.

If the panel says "GitHub isn't available on this Align platform yet", Align's app is not set up on this platform. Contact support@alignsoft.us.

A workspace's connection points at one GitHub account at a time. If you install on a different account, the connection moves to it, and repository links on the previous account are paused until you connect that account again.

The GitHub App Configuration panel in Settings → Integrations, showing the 'Install to GitHub Org' button, the Connected Organizations table and User Mappings.

One GitHub account, several workspaces

The same GitHub account can serve several Align workspaces. Each workspace connects it separately, and each sees only the accounts it connected itself.

• If the account is already connected to another Align workspace, you can connect it to yours only if you are also an admin of a workspace that uses it.
• Each workspace keeps its own repository links and its own user mappings.
• Disconnecting the account from one workspace does not affect the others.

Linking repositories to projects

Admins and managers can link repositories. You can do it in the GitHub step of the new-project wizard, or later from the project's settings:

1. Open the project's settings and go to the Integrations tab.
2. Under Linked Repositories, click Link Repository.
3. Choose the GitHub Organization, then the Repository.
4. Click Link Repository.

Only accounts your workspace has connected are offered. A repository can be linked to more than one project.

Each linked repository shows its branch, the time of its last event and its status. A Stale badge means no event in the last 24 hours; No events means none has arrived yet. The row's buttons let you:

• sync the last 90 days of history;
• verify that GitHub is delivering events for the repository;
• set the repository as the project's primary one;
• unlink it.

The 'Link a Repository' dialog, with a GitHub Organization picker and a Repository picker.

How commits and pull requests link to entries

Align reads entry references written as ALN- followed by the entry number, for example ALN-42. Case does not matter.

Where the reference is	What Align does
Commit subject line, or the branch name	Links the commit as work on the entry. If the commit's author maps to an Align user, Align comments on the entry: "Commit abc1234 linked automatically — commit subject".
Commit message body, mentioned in passing	Links the commit for traceability only. It does not count as work on the entry.
Pull request title, or its branch name	Links the pull request as work on the entry.
Pull request description, with a closing keyword (Closes ALN-42, Fixes ALN-42, Resolves ALN-42)	Links the pull request and marks it as finishing the entry.
Pull request description, mentioned in passing	Ignored.

A closing keyword counts only when it is a claim:

• closes, closed, fixes, fixed, resolves and resolved count anywhere in a sentence.
• close, fix and resolve, and any form of implement, complete or deploy, count only on a line of their own that ends with the reference, such as Implements ALN-42.
• A negation or an article before the keyword cancels it: "does not fix ALN-10" and "the fix ALN-3 applied" are not claims.

The same rules apply to closing keywords in a commit message body.

An entry's GitHub Activity card lists its linked commits, pull requests (with their state and CI result) and deployments. Link commit on that card searches the project's commits by SHA or message so you can link one by hand. Linking by hand works only where Align has switched on verified linking for the platform and the project has Enable verified-identity attribution & manual linking turned on, under GitHub Advanced (V1) in its Integrations tab.

The GitHub Activity card on an entry, listing a linked pull request with its state and CI badge, and two linked commits with SHA, author and branch.

What moves entries

Align moves an entry only when a change claims it, as described above. Entries that are Deployed, Done or Solved are never moved.

Merged pull requests

When a pull request is merged, Align adds a comment naming it to each entry it references that is not Done or Solved.

Status changes on merge are a per-project setting: Enable Auto-Status under GitHub Auto-Status on PR Merge in the project's Integrations tab. It is off by default. When it is on:

The merged pull request…	The entry moves
names the entry in its title or branch	from Open or Assigned to In Progress
closes the entry (closing keyword)	from Open, Assigned, In Progress, Blocked or Testing to the project's Target Status: Deployed (the default) or Solved

Only merges into the repository's linked branch, the branch shown on its row under Linked Repositories, change status. A merge into another branch (for example Testing) still links the pull request and comments on the entry, but doesn't move it.

Project members are notified when Align changes an entry's status this way.

Deployments

Successful deployments that GitHub reports, and Railway deploys (see Railway Integration), move the entries they carry: entries linked to the deployed commit, and entries referenced in the deployment's branch or description. The claim rules above apply: a reference in a description counts only with a closing keyword.

Align matches the deployment to one of the project's environments (the project's Environments tab) by name. An environment with Production on is production, and a matched environment without Production on is always a testing deploy, whatever its name. The name rules apply only to deploys that match no environment: a name containing "prod" is production, and a name containing "test", "stag", "qa" or "uat" is a testing deploy.

Deployed to	Change names the entry	Change closes the entry
Production	Open or Assigned → In Progress	Open, Assigned, In Progress, Blocked or Testing → Deployed, if the health check passes
Testing or staging	Open, Assigned or In Progress → Testing	Open, Assigned or In Progress → Testing
Anything else (for example a preview)	Open or Assigned → In Progress	No change

The health check: when a production deployment reports a URL, Align requests /api/health on it. If that request fails, the entry is not moved to Deployed.

Turning off Advance entries on deploy on an environment stops deployments to it from changing statuses. Align still records the deployment on the entry. Notify on advance controls the notification sent when an entry reaches Deployed.

Check runs and CI

Align reads CI results from linked repositories: GitHub check runs, check suites and GitHub Actions workflow runs. The result appears on the pull request in the entry's GitHub Activity card.

Align can also post check runs to GitHub:

• Align CI. In the project's Integrations tab, Testing / CI has a switch per linked repository. When it is on, a GitHub Actions workflow can send test results to Align. Align records the run, lists it under Recent Test Runs, and posts a check run on the commit (named Align CI by default). With Merge Policy (default) set to Informational, failing tests show as neutral. With Required, failing tests fail the check.
• Align Traceability. A check that a pull request is linked to an entry. It is off unless Align has switched on Traceability for your workspace and set the repository's check mode; there is no setting for it in the app. A linked pull request passes. An unlinked one is either flagged as advisory or fails, depending on the mode. The label align/exempt exempts a pull request.

Where Align has switched on GitHub V2 for the platform and the project has that same manual-linking switch on, Testing / CI also offers Commit-level gating (push), per-environment merge policy overrides and flaky-test overrides.

Comment sync

Sync comments to GitHub PRs, under Comment Sync in the project's Integrations tab, is off by default. When it is on, comments on an entry with a linked pull request are posted to that pull request, and pull request comments come back to the entry. Internal comments and AI-generated comments are not posted to GitHub.

User mappings

A user mapping tells Align that a GitHub login belongs to an Align user, so their commits and pull requests are credited to them. Mappings belong to the workspace. Another workspace connected to the same GitHub account keeps its own mappings, and may map the same login differently.

User Mappings appears in the GitHub panel once an account is connected:

• Mapped Users lists each GitHub user, the Align user it maps to, and the mapping's source.
• Unmapped Contributors lists GitHub logins that have committed to your linked repositories, with their commit count. Where the commit email matches an Align user, the Suggested Match column shows them with an email match badge.

To map one contributor, click Link, choose the Align User, and click Link User. To map several at once, tick them and click Map selected, or click Map all email matches. Only active members of your workspace can be chosen.

Creating a mapping credits that login's existing commits and pull requests in your workspace's projects. Deleting a mapping removes that credit, in your workspace only.

Who gets credit

For each commit and pull request, Align credits the first of these that applies:

1. A GitHub account the person connected themselves (see below).
2. Your workspace's mapping for the login.
3. A link to the same person that an admin made elsewhere in Align, if your workspace has no mapping for the login.

Only active members of the project's workspace are credited. If a candidate is not a member, Align tries the next. By default, a matching email address alone does not credit a commit; it only produces the email match suggestion.

Connecting your own GitHub account

Team members can connect their own GitHub account, so their commits and pull requests are credited to them without an admin mapping. This is available only where Align has switched on verified linking for the platform.

1. Open your profile settings, go to the Integrations tab, and click Manage integrations.
2. On the GitHub card, click Connect with GitHub (or Connect another account).
3. Approve access on GitHub. You return to Align with the account listed.

Align then maps your login in each of your workspaces that has a GitHub account connected, and credits your existing commits and pull requests there. A mapping an admin already made for your login is left as it is.

If the card says Verified linking not enabled, ask an admin to map your GitHub login instead.

Disconnecting your account from the card removes the mappings it created. Credit for your commits and pull requests is removed in the workspaces where you are still an active member. Mappings an admin made are kept.

Disconnecting GitHub from a workspace

• Turn off the GitHub switch in Settings → Integrations. The connection is disabled and the workspace's repository links are paused (they show as Inactive). Turning the switch on again resumes them.
• Remove the account: click the delete button on its row under Connected Organizations. The account is disconnected from this workspace only, and its repository links are paused.

In both cases:

• Commit and pull request history stays in Align, and so does the credit already given to people.
• Your user mappings are kept, and apply again when you reconnect.
• No new events from that account reach the workspace while it is disconnected.
• Reconnecting the same account resumes the paused repository links.

Removing the account in Align does not uninstall Align's app from GitHub. To uninstall it, do so in GitHub's settings. Uninstalling on GitHub cuts off every Align workspace that uses that account.

Webhooks

GitHub sends events to Align through Align's app. You do not set up webhooks yourself. Align processes pushes, pull requests, comments on pull requests and issues (not inline review comments), check runs, check suites, workflow runs and deployment statuses for linked repositories.

Release evidence

On a release, staff see a Release Evidence panel. It lists each entry's linked commits and pull requests, with CI results, and can be downloaded. See Releases.

The Release Evidence panel on a release, showing commits, pull requests and CI results grouped by entry.