The Linear integration creates a [Linear Release](https://linear.app/docs/releases) in a release pipeline of your choice every time a DeployHQ deployment finishes. Releases are a Linear concept that tie a set of shipped issues to a specific commit, so this integration is most useful for teams that already use Linear's Releases feature to track what went out in each deploy.

Linear Releases require a Business or Enterprise plan in Linear. The integration will not work on Free or Standard plans because the underlying `releaseCreate` mutation is not available there.

## 1. Generate a personal API key in Linear

In Linear, click your workspace avatar and open **Settings**. Under the **My Account** section in the left-hand menu, click **API**. In the **Personal API keys** area, click **Create key**, give it a recognisable label (for example, "DeployHQ"), and copy the generated key. Linear will not show this key again, so paste it somewhere safe before leaving the page.

If you only want this integration for one workspace, the personal API key inherits your account's access to that workspace. For a team-owned setup, generate the key from a service account in Linear instead.

## 2. Find the pipeline ID

You will need the ID of the Linear release pipeline you want DeployHQ to publish to.

In Linear, go to **Settings** > **Releases** and open the pipeline you want to use (or create one). The pipeline's UUID is the last segment of the URL when you have it open, for example `https://linear.app/your-workspace/release-pipelines/8a1b2c3d-...` — the part after `release-pipelines/` is the value to copy.

If you prefer not to dig in URLs, you can also list your pipelines via the Linear API:

```bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: YOUR_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { releasePipelines { nodes { id name } } }"}'
```

Note that the Linear API uses the raw key in the `Authorization` header, with no `Bearer` prefix.

## 3. Add the integration in DeployHQ

In your DeployHQ project, click **Integrations** in the left-hand menu, then **New Integration**, and pick **Linear** from the service grid.

Fill in:

- **Personal API Key**: the key you generated in step 1.
- **Pipeline ID**: the UUID you copied in step 2.
- **Environment** (optional): a label such as `production` or `staging`. Used only for the `%environment%` token in the release name template below — DeployHQ does not send this to Linear directly.
- **Release Name Template** (optional): the format of each release's name in Linear. Defaults to `%project% %endrev%`. You can use any of the standard DeployHQ template variables here, including `%endrev%`, `%branch%`, `%project%`, `%environment%`, `%deployer%`, and `%tag%`.

Choose when to trigger the integration — typically **on successful deployments** — and pick the servers it should fire for, then click **Create Integration**.

## 4. Verify the release appears in Linear

Trigger a deployment in DeployHQ. A few seconds after it finishes, open the pipeline in Linear and refresh — a new Release should appear with the templated name, the deploy's commit SHA, and a description pointing back to your repository.

## What gets sent to Linear

For every deployment, DeployHQ creates one Linear Release with these fields:

- **Name**: built from your name template (default `%project% %endrev%`).
- **Pipeline**: the pipeline you configured.
- **Commit SHA**: the deployment's `end_revision`, the full 40-character SHA.
- **Version**: a short eight-character version of the same SHA, used as the visible release label in Linear.
- **Description**: `Deployed via DeployHQ — <repository URL>@<SHA>`.

The integration uses Linear's GraphQL API and authenticates with a personal API key in the `Authorization` header, with no `Bearer` prefix.

## Known limitations

- **Linear's `releaseCreate` mutation is currently marked `[ALPHA]` in their schema.** The integration follows Linear's documented API shape, but the contract is not yet General Availability. If Linear changes the mutation, this integration may need to be updated.
- **GraphQL errors are not surfaced.** If Linear rejects the request — for example, because of an expired API key, an invalid pipeline ID, or a schema change — its API returns HTTP 200 with the error in the response body rather than a 4xx status. DeployHQ does not currently inspect that response body, so the deployment's notification log will show the integration as delivered even though no Release was actually created. **If a Release does not appear in Linear after a deployment, double-check the API key and pipeline ID first.** We are tracking improved error reporting for this case.

## Removing the integration

If you stop using Linear, or want to switch pipelines, open **Integrations** in the left-hand menu, click the Linear integration's row, and use **Delete**. Existing Releases in Linear are not affected.