Integrations

Crates are designed to link to your existing issue tracker - the place where detailed technical discussion, sub-tasks, and implementation notes live. Agile Flights integrates with GitHub and JIRA Cloud so you can search and link issues directly when loading crates onto a flight, without leaving the app.

Connecting an Integration

Integrations are set up at the organisation level. Head to Settings > Integrations to see the available platforms. Only organisation owners can connect or disconnect integrations - if you're not an owner, you'll see a message asking you to contact one.

Once an integration is connected at the organisation level, it becomes available to all teams in the organisation. Individual teams can then enable or disable each integration independently from Team Settings > Integrations. This gives teams control over which search buttons appear when their members are loading crates.

GitHub

The GitHub integration uses a GitHub App installation. Click Install GitHub App on the Integrations page and you'll be redirected to GitHub to authorise the app for your organisation's repositories. Once installed, the integration appears as connected and you can toggle it on or off.

With GitHub connected, a Search GitHub button appears when adding crates to a flight. Type a query and the app searches your repositories for matching issues, pull requests, and projects. Select a result to auto-populate the crate's URL, description, and linked reference.

JIRA Cloud

The JIRA integration connects to your Atlassian Cloud instance using your domain, email address, and an API token. Unlike the GitHub integration which uses an app installation, JIRA uses token-based authentication - so you'll need to generate an API token from your Atlassian account before getting started.

Finding Your JIRA Domain

Your JIRA domain is the URL you use to access JIRA in your browser - typically something like your-company.atlassian.net. You can find it by opening JIRA and looking at the address bar. Enter just the domain, not the full URL. For example, if your JIRA board is at https://acme-corp.atlassian.net/jira/board, your domain is acme-corp.atlassian.net.

Generating an API Token

JIRA API tokens are managed through your Atlassian account security settings. Go to id.atlassian.com/manage-profile/security/api-tokens and click Create API token. Give it a descriptive label like "Agile Flights" so you can identify it later. Copy the token immediately - Atlassian won't show it again.

Use the email address associated with your Atlassian account when entering credentials in the connect form. The email and token work together as a pair.

Connecting JIRA

In Settings > Integrations, find the JIRA card and enter your domain, email, and API token. Click Validate & Select Projectsto verify your credentials against the JIRA API. If validation succeeds, you'll see a project picker showing all the JIRA projects your account has access to.

Select the projects you want to be searchable when loading crates. You don't have to select all of them - only pick the projects relevant to your team's work. This keeps search results focused and avoids noise from unrelated projects. Click Connect to save the integration.

Once connected, the JIRA card shows a "Connected" badge along with your domain and the linked project keys. You can disconnect and reconnect at any time to update the project selection.

Using JIRA Issues in Flights

With JIRA connected and enabled for your team, a Search JIRA button appears alongside any other enabled integrations when adding crates to a flight. Click it and start typing to search for issues across your selected projects. Results show the issue key (e.g. PROJ-123) and title.

Select an issue to automatically populate the crate's URL, description, and linked reference. The crate badge on the flight card displays the JIRA issue key with a kanban icon, making it easy to distinguish JIRA-linked crates from GitHub-linked ones at a glance.

If both GitHub and JIRA are enabled for a team, both search buttons appear side by side. You can also switch to manual mode and paste a URL directly - the integration search is a convenience, not a requirement.

Team-Level Controls

Each team can independently enable or disable integrations that have been connected at the organisation level. This is managed from Team Settings > Integrations, where team admins will see a toggle for each available platform.

Disabling an integration for a team removes the corresponding search button from the crate input for that team's flights. Existing crates that were already linked via that integration remain unchanged - disabling only affects future searches. This is useful when a team uses GitHub but not JIRA, or vice versa. Each team gets exactly the tools they need, nothing more.

Crate Status Indicators

When your flight has crates linked to GitHub issues or pull requests, Flights pulls the current status of each linked item and surfaces it visually across the interface. These indicators give crews and captains a quick read on the state of the work without leaving the app.

On the dashboard, each flight strip displays a small completion badge showing how many crates are complete. When all crates are done, the badge turns green - a clear signal that the flight is cargo-clear and ready to land. This lets anyone scanning the dashboard instantly see which flights are on track and which still have work in the hold.

Inside the flight detail pane, the crates panel gives more granular visibility. A colour-coded status dot sits next to each crate, reflecting the current state of its linked issue or pull request - open, in progress, merged, done, or similar states depending on your integration. The panel header also shows a running completion count, for example "Crates (2/4 complete)", so you can assess progress at a glance without counting rows.

Status information syncs automatically when you open a flight, but integrations do not push updates in real time. If you know something has changed in GitHub or JIRA and want to see the updated state immediately, use the Refresh Status button in the crates panel header. This triggers an on-demand sync and updates all status dots and the completion count straight away.

Auto-Landing

Auto-landing automatically transitions a flight to "landed" status when all of its linked crates reach a done state - completed, merged, or closed in the source platform. Instead of manually landing a flight after the last pull request is merged or the final JIRA issue is closed, the system detects the completion and lands the flight for you.

Auto-landing only applies to flights in active or emergency status. Flights that are still in takeoff, already landed, or archived are not affected.

Organisation-Level Switch

There is a master auto-landing toggle in Settings > Integrations, visible to organisation owners. This acts as an organisation-wide override:

• Enabled (default) - teams can control auto-landing per integration using their own toggles.
• Disabled - auto-landing is turned off for the entire organisation, regardless of individual team settings.

When the organisation-level switch is disabled, the per-integration toggles in team settings are greyed out. Re-enabling the organisation switch restores each team's previous per-integration preferences.

Per-Integration Toggles

Each team can enable or disable auto-landing independently for each connected integration from Team Settings > Integrations. The toggle appears below the main integration enable/disable switch for each platform.

The default settings differ by platform:

• GitHub - auto-landing is on by default. When a GitHub issue is closed or a pull request is merged, the webhook triggers an auto-land check on the associated flight.
• JIRA - auto-landing is off by default. Teams can enable it if their workflow benefits from automatic landing based on JIRA issue transitions.

How Auto-Landing Works

When a webhook update arrives from an integrated platform - for example, a GitHub issue being closed - the system updates the linked crate's status and then checks whether all crates on the flight are now done. If they are, and auto-landing is enabled for that integration at both the organisation and team level, the flight is automatically transitioned to "landed" status.

For example, imagine a flight with three crates: two linked to GitHub issues and one linked to a JIRA ticket. If the team has auto-landing enabled for GitHub but disabled for JIRA, closing the two GitHub issues will update those crates but won't trigger a landing check from the JIRA side. The flight will only auto-land when the final crate update comes from a platform that has auto-landing enabled.

Security

API tokens for JIRA are stored server-side only. The token is saved in an encrypted column that is never exposed to the browser - it's only accessible by server-side edge functions using the service role key. The client application cannot read, display, or transmit the stored token after the initial connection.

All integration searches go through a server-side proxy that validates the user's authentication before making any requests to external APIs. The proxy also includes SSRF prevention and input sanitisation to protect against malicious domain or query injection.

For authentication-related settings - including Google SSO, domain verification, and SSO enforcement - see the Authentication & SSO page.