# Integrations

Connect Andon to the trackers and accounts your teams already use, so linked issues show their state on cards, issues can come in as cards, and Andon can update an issue as its card moves. Everything is under **Settings → Connections**. Everyone sees what is connected;
owners and admins connect, change and disconnect.

| Connect | So that |
|---|---|
| **GitHub** | issues and pull requests on cards show their titles, states, checks and reviews, and runs can open, review and merge pull requests |
| **Linear** | Linear issues on cards show their state, import rules turn a team's backlog into cards, and cards write back |
| **Jira** | Jira issues on cards show their state, you can import them, and cards write back |
| **Asana** | a whole Asana team can move to Andon and stay in sync, and cards write back |
| **Trello** | a Trello board can be imported, with its comments and files |

Moving a whole team from another tracker in one go is a separate, one-time step: see
[Import from a tracker](https://andon-docs.pages.dev/guide/import-from-a-tracker.md).

## The Connections page

**Settings → Connections** lists each account once, with the teams that use it and its state: *Connected as …*, *Not
connected*, or *Needs attention* when its saved token stopped working. GitHub and Linear are always listed; Jira,
Trello and Asana appear once connected.

- **Add a connection** connects another Linear workspace, Jira, Trello or Asana, or opens **Import from a tracker**.
- **Developer** holds API tokens and webhooks ([the public API](https://andon-docs.pages.dev/reference/api.md)) and capture tokens
  ([Capture](https://andon-docs.pages.dev/guide/capture.md)).
- **Advanced** holds the workspace's own [AI keys](#ai-keys).

A token you save is checked with the provider, stored encrypted and never shown again.

## Connect GitHub

1. Make a fine-grained personal access token in GitHub (**Settings → Developer settings**), with read access to the
   repositories you link.
2. Open **Settings → Connections → GitHub**, paste the token and press **Connect**.

Public repositories resolve without a token.

## Connect Linear or Jira

1. Open **Settings → Connections → Linear** and press **Connect Linear**. For Jira, press **Add** beside **Add a
   connection**, choose **Jira**, and press **Connect Jira**.
2. Paste the token: Linear's **Personal API key** (Linear → **Settings → API**), or for Jira the **Jira site**,
   **Account email** and an **API token** (Atlassian account settings → **Security → API tokens**). Imports and
   write-back act as this account. The Jira site must be `https://` on a public address; a Jira on your own network
   needs the server's [`ANDON_ALLOW_PRIVATE_NETWORK`](https://andon-docs.pages.dev/reference/env.md) switch.
3. Add the **Key prefixes** your issues use, such as `ENG`, so a bare key like `ENG-123` on a card links to the issue.
4. Turn on the [write-back](#write-back) switches you want. Each saves at once.

### Several connections, one per team

A workspace can have several Linear or Jira connections, such as a second Linear workspace or a client's Jira site.
**Add a Linear connection** adds another. One of them is the **Workspace default**, used by every team that picks no
other.

A team picks its own on its page:

1. Open **Settings → Teams**, pick the team, and open its **Issue tracker** section.
2. Pick the connection, then the Linear team or Jira project keys inside it.
3. Press **Save**.

A team that picks nothing follows its parent's pick, else the default. **Connect another…** in the list connects a
new account without leaving the team page. A team with its own write-back switches shows them here; **Use the connection's** drops them and follows the connection.

**Disconnect** on a connection names the teams it affects and asks first.

## Write-back

Write-back sends a card's progress to its **primary** linked issue: the first tracker issue on the card. Every switch
is off until you turn it on.

| Tracker | Switch | When |
|---|---|---|
| GitHub | Close the primary issue when the card moves to Done | the card reaches Done |
| Linear | Move the primary issue to In Progress when a run starts | a run starts on the card |
| Linear | Attach pull requests to the primary issue | a run opens a pull request |
| Linear | Move the primary issue to Done when the card moves to Done | the card reaches Done |
| Linear | Set the primary issue's project milestone when a card's milestone changes | you change the milestone (milestones imported from Linear) |
| Jira | Move the primary issue to In Progress when a run starts | a run starts on the card |
| Jira | Add pull requests as remote links | a run opens a pull request |
| Jira | Move the primary issue to Done when the card moves to Done | the card reaches Done |
| Jira | Set the primary issue's fix version when a card's milestone changes | you change the milestone (versions imported from Jira) |
| Asana | Move the task to its status's section, and complete it when the card moves to Done | the card changes column or status |
| Asana | Assign the task to the card's owner | the card's owner changes |
| Asana | Post comments made on the card to the task | a person or a run comments |
| Asana | Create a task for a card made in a project imported from Asana | you make a card there |

**PR groups.** A pull request that ships several cards belongs to each of them. With the pull request switch on, it is
linked to every card's issue, including a card that joins later; on Linear each issue also gets a comment naming the
pull request and the other issues shipping with it. The merge moves every card to Done, and with the Done switch on,
each issue is closed as its card gets there. A group never sets an issue's parent.

## Linear

### Bring issues in

- **Browse Linear**: the board's **Import** button, **From Linear…**. Pick a Linear team, or under **Linear team or
  view** pick **My issues** (the issues assigned to the connection's account, which on a shared connection is whoever
  connected it) or a view saved in Linear. Tick issues and import them, or use **Import the whole view** / **Import all
  my issues**. **Cards go to** sets the team, project and column.
- **Import rules**, on **Settings → Connections → Linear**: a rule keeps importing a Linear team's issues into a
  board team and column as they appear, narrowed by state, assignee, labels or Linear project, and says what happens
  **When the issue closes**. An *Import rule failing* attention item's **Open rule** lands on that rule.
- **Linear projects**: **Import projects from Linear…** on a team's menu in the sidebar lists the Linear team's
  projects. Ticked ones become projects of the board team, with their name, description, status, dates, colour and
  lead. With **Also import their open issues as cards** on (the default), their open issues come too. Importing the
  same Linear project again finds the one already on the board. A project page has **In Linear** to open it there.

An issue imported into a team lands in the project imported from its Linear project, else the rule's or browser's
project, else the team's General.

### Keep a card up to date

A card with a Linear issue in its **Links** has **Update from Linear** on that row: the card's title and notes become
the issue's again, the issue's images are attached, and its dependencies are synced. When the issue waits for or
blocks issues not on the board, the toast offers **Import it** or **Import N**. In Browse Linear, ticking issues
already *On the board* turns the button into **Update N cards**.

### Comments from Linear

A card made from a Linear issue brings the issue's comments with it, once, up to 500. Each shows its author and a
**Linear** tag that opens it in Linear. From then on the card's own Comments tab is the conversation: later Linear
comments aren't pulled, and nothing written on the board goes back. Bringing old comments in notifies nobody. A
comment's author is the member with the same email, else a former member by name. See [Comments](https://andon-docs.pages.dev/guide/comments.md).

## Jira

The board's **Import** button, **From Jira…**, opens **Browse Jira**: pick the connection and Jira project, search,
tick issues, and choose where **Cards go to**. A Jira project maps to a board team.

A Jira **epic** becomes a project of the team, and its issues go in it; the same epic is one project per board. The
one-time [tracker import](https://andon-docs.pages.dev/guide/import-from-a-tracker.md) can map epics to parent cards instead, or ignore them.

## Dependencies from Linear and Jira

Importing brings dependencies along: Linear's *blocks* / *blocked by* and Jira's *Blocks* links. When both issues are
cards, the blocked card shows **Blocked by** the other and waits for it. Whichever issue comes in second makes the
link. A dependency the tracker drops is removed on the next import; one you add on the board stays. One you remove
comes back on the next import while the tracker still has it. Related, duplicate and clone links aren't dependencies.
How waiting works is in [Sub-tasks and relations](https://andon-docs.pages.dev/guide/subtasks-and-relations.md).

## Milestones

A Linear project milestone or a Jira fix version becomes a milestone on import, and the milestone write-back switch
sends a card's milestone back. See [Milestones from Linear and Jira](https://andon-docs.pages.dev/guide/planning.md#milestones-from-linear-and-jira).

## Asana

Connect Asana once for the whole workspace, as an owner or admin, on **Settings → Connections → Asana**:

- **Personal access token**: from Asana → **My settings → Apps → Developer apps**. Andon acts as that account.
- **Sign in with Asana**: press **Connect with Asana** and approve in Asana. This is offered only when the server has
  an Asana app set up ([environment variables](https://andon-docs.pages.dev/reference/env.md#integrations-and-push)). Give the app the redirect
  URL `<your board>/settings/integrations/asana`.

If Asana stops accepting the connection (access removed in Asana), it shows *Needs attention*: connect again.

Asana's [write-back](#write-back) switches act on cards whose primary link is an Asana task, which in practice means
cards from an Asana import. Write-back needs write access to tasks and stories. Nothing the import or its sync writes
is sent back, so the two never echo each other. Keeping an import in sync, Asana to Andon, is in
[Import from a tracker](https://andon-docs.pages.dev/guide/import-from-a-tracker.md#keep-an-asana-import-in-sync).

### Asana sync health

Below write-back, owners and admins see how the sync stands. **Refresh** reads it again.

- **Sync health**: each Asana import (the latest 20), how many of its projects are listening, when Asana's changes
  last arrived, how many changed tasks wait, and the last error. In a word: *In sync*, *Connecting*, *Syncing n
  changes*, *Needs attention* or *Not syncing*. A row opens the import.
- **Write-back log**: the latest 50 write-backs (kept a week): *Sent*, *Nothing to send*, *Skipped*, *Failed* with
  Asana's reason, or *Never sent*. **Problems** keeps the failed ones.

## Trello

Trello is for importing a board. On **Settings → Connections → Trello**, save an **API key** (from
[trello.com/power-ups/admin](https://trello.com/power-ups/admin)) and a **Token** from the authorize link beside it,
with read access. With them, [Import from a tracker](https://andon-docs.pages.dev/guide/import-from-a-tracker.md) reads a board with every comment and
copies its files. Nothing on cards links to Trello.

## AI keys

Under **Settings → Connections**, **Advanced**:

- **AI backend** picks how the assistant, attention triage, [recipe](https://andon-docs.pages.dev/guide/recipes.md#how-a-card-gets-its-recipe) picking,
  Autopilot placement, Start work and Auto-Done call a model: **Deployment default**, **Claude (Anthropic API)**,
  **Vercel AI Gateway**, **Gemini directly** or **On a machine**. Admins change it. With an Anthropic key, the
  deployment default is Claude.
- **Voice model (AI Gateway)** sets the model voice uses through the gateway. Voice never runs on Claude or a machine.
- **Claude (Anthropic) key**, **Gemini key** and **Vercel AI Gateway key** are this workspace's own keys. Without one,
  the server's key is used.

[AI backends](https://andon-docs.pages.dev/machines/ai-backends.md) says what each backend needs.

## See also

- [Import from a tracker](https://andon-docs.pages.dev/guide/import-from-a-tracker.md): move a whole team, once.
- [Integrations internals](https://andon-docs.pages.dev/contributing/integrations-internals.md): how connections are stored and write-back runs.
