@linear/release-action

GitHub Action for syncing deployments with Linear releases

Connect your deployments to Linear releases.
Automatically link issues to releases.

Overview

This action wraps the Linear Release CLI to integrate your CI/CD pipeline with Linear's release management. It automatically scans commits for Linear issue identifiers, detects pull request references, and creates or updates releases in Linear.

For full documentation on pipeline types, how commit scanning works, path filtering details, and troubleshooting, see the Linear Release CLI README. This README covers the GitHub Action-specific configuration.

Quick Start

permissions:
  contents: read

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0 # Required for commit history

  - uses: linear/linear-release-action@v0
    with:
      access_key: ${{ secrets.LINEAR_ACCESS_KEY }}

AI-assisted setup

Use the Linear Release setup skill to generate CI configuration tailored to your project. It walks you through continuous vs. scheduled pipelines, monorepo path filtering, and more.

Copy the SKILL.md into your project, or install it with skills.sh:

npx skills add linear/linear-release

Once installed, run it from your AI agent with /linear-release-setup (or just ask the agent to set up Linear Release — it will pick up the skill automatically).

Inputs

Input	Required	Default	Description
access_key	Yes		Linear pipeline access key for authentication
command	No	sync	Command to run: sync, complete, or update
name	No		Custom release name. For sync, the value is applied to the targeted release — both newly created releases and existing ones get the provided name. For complete and update, sets the name on the targeted release.
version	No		Release version identifier (alias: release_version)
stage	No		Deployment stage such as staging or production (required for update)
include_paths	No		Filter commits by file paths (comma-separated globs for monorepos)
base_ref	No		Override the sync scan base. Exclusive: scans <base_ref>..HEAD
links	No		Links to attach to the targeted release, one per line. Each value must be either an absolute URL or Label=URL.
log_level	No		Log verbosity: quiet or verbose. Omit for default output.
timeout	No	60	Maximum time in seconds to wait for the command to complete
cli_version	No	v0.12.0	Linear Release CLI version to install

Outputs

Output	Description
release-id	The Linear release ID
release-name	The Linear release name
release-version	The Linear release version
release-url	URL to the Linear release

Outputs are empty when no release is created (e.g. no matching commits found).

Using outputs

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0

  - uses: linear/linear-release-action@v0
    id: release
    with:
      access_key: ${{ secrets.LINEAR_ACCESS_KEY }}

  - name: Use release outputs
    if: steps.release.outputs.release-url
    run: echo "Release URL is ${{ steps.release.outputs.release-url }}"

Commands

sync

Creates or updates a release by scanning commits for Linear issue identifiers.

- uses: linear/linear-release-action@v0
  with:
    access_key: ${{ secrets.LINEAR_ACCESS_KEY }}

complete

Marks the current release as complete. Only applicable to scheduled pipelines, as continuous pipelines create releases in the completed stage automatically.

- uses: linear/linear-release-action@v0
  with:
    access_key: ${{ secrets.LINEAR_ACCESS_KEY }}
    command: complete

update

Updates the deployment stage of the current release. Only applicable to scheduled pipelines, as continuous pipelines create releases in the completed stage automatically.

- uses: linear/linear-release-action@v0
  with:
    access_key: ${{ secrets.LINEAR_ACCESS_KEY }}
    command: update
    stage: staging

Command targeting

Command	With version	Without version
sync	Targets matching version or creates that version	Continuous pipelines create a release with short SHA name/version. Scheduled pipelines use current started/planned flow.
update	Updates that exact release version	Updates latest started release, or latest planned release if no started release exists
complete	Completes that exact release version	Completes latest started release

For scheduled pipelines, prefer always passing version in CI, especially when releases overlap.

Path filtering

Filter commits by file paths to track releases for specific packages, useful for monorepos:

- uses: linear/linear-release-action@v0
  with:
    access_key: ${{ secrets.LINEAR_ACCESS_KEY }}
    include_paths: apps/web/**,packages/shared/**

Scan base override

Use base_ref to explicitly choose the exclusive lower bound for sync's commit scan. This is useful when the automatically selected release baseline is not the range you want for a custom branching workflow, first-time onboarding, or migration.

- uses: linear/linear-release-action@v0
  with:
    access_key: ${{ secrets.LINEAR_ACCESS_KEY }}
    base_ref: last-released-ref
    include_paths: apps/api/**

The base ref is exclusive: Linear Release scans <base_ref>..HEAD, matching Git range syntax, and still applies any configured path filters. Pass the last commit, tag, or ref that should be treated as already released, not the first commit you want included.

When base_ref is provided, it overrides automatic base selection for that run. After sync, current HEAD is stored as the future release baseline. Choosing an older or newer base can reattach or skip commits, so use this only when you intentionally want to own the scan range.

Release links

links attaches external URLs to the release — a GitHub release page, a CI run, a deployment dashboard. One link per line, as either an absolute URL or Label=URL. When the label is omitted, Linear derives it from the URL (e.g. https://github.com/... → "GitHub").

- uses: linear/linear-release-action@v0
  with:
    access_key: ${{ secrets.LINEAR_ACCESS_KEY }}
    links: |
      https://github.com/acme/app/releases/tag/v1.2.0
      Deploy dashboard=https://deploys.example.com/v1.2.0

Versioning

Each release of this action defaults to a specific Linear Release CLI version. Pinning the action — whether by tag (@v0) or commit SHA — also pins the CLI. Set cli_version to override.

Troubleshooting

"Unsupported OS" or "Unsupported arch" error

The action supports Linux (x86_64, aarch64) and macOS (x86_64, arm64) runners. Windows is not supported.

"access_key input is required" error

Ensure you've set the access_key input with your Linear pipeline access key stored in GitHub Secrets.

Issues not being linked

Make sure your commits contain Linear issue identifiers (e.g., ENG-123) and that actions/checkout uses fetch-depth: 0.

name is ignored on non-sync commands

If name is provided with command: update or command: complete, the action prints a warning and continues. Use name with command: sync only.

License

MIT - see LICENSE