GitHub

The GitHub integration lets you connect your code repositories with Almirant to link pull requests and commits to work items, view development activity directly from the board, and give AI agents context about the project's code.

Prerequisites

The GitHub integration is controlled by a feature flag. For it to be available in your Almirant instance, the NEXT_PUBLIC_FEATURE_GITHUB environment variable must be enabled.

Connecting GitHub

The connection is made through a GitHub OAuth App installation at the organization level:

1. Go to Settings > Integrations > GitHub.
2. Click Connect GitHub.
3. GitHub will ask you to authorize Almirant as an OAuth App.
4. Select the organization or account where you want to install the application.
5. Choose the repositories that Almirant will have access to (all or selected).
6. Confirm the installation.

Once completed, you'll see the connection status and available repositories in the integrations settings.

Selected repositories

We recommend granting access only to the repositories you plan to link with projects in Almirant, rather than granting access to all of them. You can modify permissions later from your GitHub settings.

Linking repositories to a project

Once GitHub is connected, you can link one or more repositories to each project:

1. Navigate to the project where you want to link repositories.
2. Go to the Repositories section.
3. Click Link repository.
4. Select the repository from the list of available repositories.
5. Confirm the link.

The repository is now associated with the project and all its activity will be visible from Almirant.

Pull requests and work items

One of the most useful features of the integration is the automatic linking between pull requests and work items.

How to link a PR to a work item

Include the work item identifier (for example A-T-42) in the title or description of the pull request on GitHub. Almirant will detect the reference and link the PR automatically.

Example PR title:

feat: Implement notification system [A-T-42]

Example in PR description:

## Description
Implements the push notification system.

Related to: A-T-42

Viewing PRs from Almirant

From a work item's detail view, you can see all linked pull requests with:

• PR status (open, closed, merged).
• Author and creation date.
• Direct link to the PR on GitHub.

Viewing associated commits

In addition to pull requests, Almirant shows the commits associated with the work item, providing full traceability of the code linked to each task.

Development activity

In the project view, the repositories section shows a summary of recent development activity:

• Latest commits on the main branches.
• Open pull requests and their status.
• Team member activity across repositories.

Context for AI agents

When a repository is linked to a project, AI agents can access the code context to:

• Understand the project structure when implementing new features.
• Review existing code during a code review.
• Generate tests based on the current implementation.
• Answer technical questions with knowledge of the actual codebase.

Disconnecting GitHub

To disconnect the GitHub integration:

1. Go to Settings > Integrations > GitHub.
2. Click Disconnect.
3. Confirm the disconnection.

warning

Disconnecting GitHub will remove the repository links with projects. Work items will retain historical references to PRs and commits, but they will no longer be updated with new information.

For Developers

Environment variables

Variable	Description	Required
NEXT_PUBLIC_FEATURE_GITHUB	Feature flag that enables the GitHub integration on the frontend	Yes
GITHUB_CLIENT_ID	Client ID of the GitHub OAuth App	Yes
GITHUB_CLIENT_SECRET	Client Secret of the GitHub OAuth App	Yes

Integration architecture

The integration consists of:

• Frontend: github domain in frontend/src/domains/github/ with hooks for OAuth installation and repository linking.
• Backend: Routes in backend/api/src/routes/ for managing installations and repositories.
• Database: githubInstallations and repositories tables in the schema.
• Webhooks: Endpoint that receives GitHub events (push, PR) and updates the information in Almirant.