Skip to main content
Table of Contents

LinearB Deployment API

LinearB’s Deployment API lets you report release and deployment events from your CI/CD pipeline. When a deployment is reported, LinearB determines exactly which branches were included using Git ances…

Steven Silverstone
Updated by Steven Silverstone
Table of Contents

LinearB’s Deployment API lets you report release and deployment events from your CI/CD pipeline. When a deployment is reported, LinearB determines exactly which branches were included using Git ancestry logic — not timestamps.

This ensures accurate deployment timestamps, closes cycle time only when work is truly shipped, and prevents unrelated merged branches from being marked as deployed.

The Deployment API is typically used by CI/CD systems and requires API access to be enabled for your LinearB organization.
Summary
  • Report deployments from your CI/CD pipeline to LinearB.
  • Send the deployed commit SHA or Git ref for each release.
  • LinearB determines deployed branches using Git ancestry.
  • Supports monorepos, services, and custom deployment stages.
Before you begin

What you’ll need

  • API access enabled for your LinearB organization
  • Ability to send a deployed ref_name or commit SHA from your pipeline
  • (Optional) Service name if reporting deployments for a specific service in a monorepo

Roles required

  • LinearB Admin

Estimated time

  • 15–20 minutes
Step 1 – Send a deployment event

From your deployment pipeline, send a request to the Deployment API when a deployment occurs.

HTTP request

POST https://public-api.linearb.io/api/v1/deployments

Required body parameters

Parameter Type Description
repo_url string The Git repository URL (must include .git for qualified URLs)
ref_name string The deployed Git reference (commit SHA, tag, or ref name). This is the authoritative version used for ancestry matching.
timestamp ISO 8601 string The time the deployment (or pre-deployment stage) occurred
stage string (lowercase) Deployment stage identifier.
Default production stage: release
services array of strings Optional service names for monorepo deployments
How LinearB determines which branches were deployed

When a deployment event is received, LinearB performs the following steps:

  1. Identifies the deployed version using the provided ref_name or commit SHA.
  2. Collects all branches currently in the merged state.
  3. Runs a Git ancestry check:
    git merge-base --is-ancestor
  4. If the branch commit is an ancestor of the deployed ref:
    • The branch is marked as deployed
    • Cycle time is closed
    • The branch is linked to the deployment event
LinearB does not assume all merged branches are deployed. Inclusion is determined strictly by Git ancestry — not by timestamps.
Timing and ordering considerations
  • LinearB does not use merge or deployment timestamps to decide inclusion.
  • A branch may be included even if its merge time is later than the deployment time.
  • What matters is whether the branch’s commit exists in the deployed ref according to Git.
Each deployment triggers a full re-evaluation of which merged branches belong to that release.
Using services (monorepo support)

When deploying a single service from a monorepo, include the services parameter.

  • Only branches that modified the specified service are considered
  • Unrelated branches are excluded from deployment marking
  • The same Git ancestry logic applies, scoped to service-level changes
ref_name and services work together to precisely control deployment matching in monorepos.
Deploying to custom stages

You can report deployments for custom pipeline stages (such as Staging, Pre-Prod, or QA).

Custom stages require enablement. Contact your account manager or support@linearb.io to configure this feature.
  • Branches remain in merged state until the final stage (release)
  • Stages are processed in a fixed order
  • Stages may be skipped, but not reverted
  • Each stage uses the same Git ancestry matching logic
Troubleshooting
Issue Cause Resolution
Branch not marked as deployed Commit not an ancestor of deployed ref Verify the deployed commit SHA or ref_name
Too many branches deployed Missing service scoping in monorepo Include correct services value
Deployment appears without branches Branches not merged at evaluation time Ensure merges completed before reporting deployment
Wrong deployment stage Incorrect stage identifier Re-send event with correct stage
FAQs

Does LinearB use timestamps to determine deployed branches?

No. LinearB uses Git ancestry logic only.

Can a branch be deployed even if merged later?

Yes, if the branch’s commit is an ancestor of the deployed ref.

Can I deploy only one service from a monorepo?

Yes. Use the services parameter.

Do custom stages change matching behavior?

No. Matching logic remains the same across all stages.

For further assistance, contact support@linearb.io or visit the LinearB Help Center .

How did we do?

Generating a LinearB API Token

Contact