Skip to main content

Deployment API

Deployment API & Release Detection. Use the Deployment API to report releases and allow LinearB to automatically determine which branches were included in each deployment. --- On this page. - Overvie…

heather.hazell
Updated by heather.hazell

Deployment API & Release Detection

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

---

On this page

- Overview

- Before You Begin

- Steps

- Troubleshooting

- FAQs

---

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 and include:

  • The commit SHA or ref_name of the deployed version  
  • (Optional) `service_name` for monorepos  

💡 LinearB does not automatically consider all merged branches as deployed.  

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

---

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 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/released state.  
    4. The branch is linked to the deployment event.

💡 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.

---

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  
  • 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 → Production).

---

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. |

---

FAQs

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

No. LinearB uses Git’s ancestry logic (`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