Skip to main content
Table of Contents

LinearB Deployment API

Use the Deployment API to report releases and allow LinearB to automatically determine which branches were included in each deployment. --- Overview. LinearB’s Deployment API lets you report deployme…

Steven Silverstone
Updated by Steven Silverstone

Use the Deployment API to report releases and allow LinearB to automatically determine which branches were included in each deployment.

---

Overview

LinearB’s Deployment API lets you report deployments and release events from your CI/CD system.  

When a deployment is reported, LinearB uses Git ancestry logic to determine exactly which merged branches were included in that release.

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

---

Before You Begin

Prerequisites

Roles Required: Admin

Estimated Time: 15–20 minutes  

---

Steps

1. Send a Deployment API Call

From your deployment pipeline, call the Deployment API

HTTP request

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

Body Parameters to Include:

Parameter Name

Value

Description

repo_url (required)

string

The git repository urlPattern: ^https://[a-zA-Z0-9./+^@_-]{15,250}$should have .git suffix for qualified urls

ref_name (required)

string

Ref name of the release, accepts any Git ref (i.e. commit short or long sha/tag name)

Pattern:^[!\"#\$%&\'()+,-0-9;<=>\@A-Z]_`a-z{ }.]{5,40}$

timestamp (required)

string (timestamp ISO 8601 format)

The deployment or custom pre-deployment stage occurred at this specific time

stage

string

(lowercase only)

The key of the custom pre-deployment stage.

Default stage for deployment to production: release

services

array of strings

The list of LinearB service names monitoring this

---

2. How LinearB Determines Which Branches Were Deployed  

After receiving a deployment event, LinearB:

  1. Looks at the version of the code that is being deployed (uses commit SHA or ref_name).
  2. Evaluates all branches in the “merged” state (candidates for inclusion).
  3. Runs a git merge-base --is-ancestor check: “Is the branch’s commit an ancestor of the deployed commit?”
  4. If true:  
    1. The changes from that branch are included in the deployed version.  
    2. Cycle time is closed.  
    3. The branch is moved into deployed state.  
    4. The branch is linked to the deployment event.

💡 LinearB does not automatically consider all merged branches as deployed. This logic is based on Git ancestry, not timestamps - A branch can be included even if its merge timestamp is later than the release time - ancestry is what determines inclusion. 

💡 Each deployment triggers a full evaluation of which branches should be included.

---

3. Timing and Ordering Considerations
  • The containing ref (the deployment commit) is usually later than the branch commits it contains.
  • LinearB is not checking the time to decide inclusion.
    •  A merged branch can have a “merged at” value that is later than the release time.
    •  What matters is whether the branch’s ref is included in the deployed ref according to Git checks.
  • LinearB relies on Git to check if one ref is included in another, not on date comparisons.

---

4. Using Services (+ Monorepo Support)

When you use services in the Deployment API, you can specify that you are deploying a specific service

This enables LinearB to:

  • Only mark branches as deployed if they touched the specified service  
  • Avoid marking unrelated PRs as deployed  
  • Apply the same Git ancestry logic, but scoped to service-specific changes

💡`ref_name` and `service_name` work together as filters for the inclusion logic.

---

5. Deploying to Custom Stages

You can send deployment events for any custom stage in your release pipeline.

Please contact your account manager or support@linearb.io in order to implement this feature.

For each stage:

  • The same Git ancestry matching is applied for all stages. 
  • A branch remains in “merged” until it reaches its final deployment (stage: release) 
  • Stages are processed in a set order  
    •   You may skip a stage  
    •    You may not revert a stage  
  • When a deployment is reported for a given stage, LinearB:
    • Looks at all branches in merged state.
    • Identifies branches that have not been deployed in any later stage.
    • Matches and exposes those branches for this deployment stage using the same is-ancestor logic.

💡This ensures accurate visibility when deployments move across multiple environments (e.g., Staging → Pre-Prod → Release).

---

Troubleshooting

Problem

Cause

Fix

Branch not marked as deployed

Git ancestry does not show the branch’s commit as an ancestor of the deployed ref

Confirm the commit SHA in the deployment API call matches the actual deployed version

Too many branches marked as deployed

Incorrect `ref_name` or missing service scoping in monorepo

Include the correct `service_name` and verify the commit represents the exact deployment

Deployment assigned to wrong stage

Deployment API called with incorrect stage identifier

Re-send the event with the correct stage name

Deployment appears but branches do not 

Branches not in “merged” state at evaluation time

Confirm branches were merged before sending the deployment event

Custom stage behavior seems off

Stage order and “no revert” rule

Check which stage the deployment was reported to and whether the branch has already been deployed to a later stage. |

For further assistance, contact support

---

FAQs

Q: Does LinearB use timestamps to determine which branches were deployed?  

No. LinearB uses Git’s ancestry logic (git merge-base --is-ancestor) to determine inclusion. Timestamps are not used in the decision.

Q: What if a branch’s merge timestamp is after the deployment timestamp?  

If the branch’s commit is an ancestor of the deployed commit, it is still considered included.

Q: Can I deploy only one service in a monorepo?  

Yes. Include `service_name` in the Deployment API call to limit deployment matching to that service.

Q: Do custom deployment stages change matching behavior? 

No. The same inclusion logic applies. Stages simply control release progression and visibility.

---

How did we do?

Contact