Skip to main content
Deutsch (Deutschland) Español Français Hebrew (Israel) Italiano Português

Deployment API

Heather Hazell
Updated

Use the Deployment API to report deployments from your CI/CD system and allow LinearB to accurately determine which merged branches were included in each release.

When a deployment is reported, LinearB uses Git ancestry (not timestamps) to decide which branches are considered deployed. This closes cycle time only when work is actually shipped and prevents unrelated merged branches from being marked as deployed.

TL;DR

  • Use POST /api/v1/deployments from your CI/CD pipeline whenever you deploy.
  • LinearB uses Git ancestry between the deployed ref (ref_name) and merged branch tips to decide what was deployed.
  • Optional fields like timestamp, stage, and services let you model environments and services (for example, staging vs. release, monorepo services).
  • Use GET /api/v1/deployments to list deployments recorded by LinearB.
  • Deployments feed into release detection, cycle time closure, and reliability metrics when combined with incident tracking.

Where to Configure API Deployment for Release Detection

Organization-wide release detection method

Set the organization-wide release detection method
  1. In LinearB, go to Company Settings → Advanced.
  2. In the Release Detection section, select API Integration.
  3. Click Save to apply your changes.

Once API Integration is selected at the organization level, deployments reported via the API are used to calculate deployment-related metrics for your LinearB environment.

Repository-level release detection method for teams

Override release detection per repo

Individual teams can use a different release detection method than the organization default. For example, the org may use tag–based releases, while a specific team uses the Deployment API.

  1. In LinearB, select the team that should use a different release detection method in the dropdown (top right).
  2. Go to Settings → Team Settings.
  3. On the Team Settings page, open the Advanced tab.
  4. In the Release Detection section, select API Integration.
  5. Click Save to apply your changes.

This affects how LinearB calculates deployment metrics for that team and any parent groups that aggregate it.

Before You Begin

Who should set this up?
  • A LinearB Admin user.
  • DevOps / Platform engineer with access to your CI/CD pipelines.
  • Someone who can safely add a call to the Deployment API into the deploy step.

Prerequisites

  • API access is enabled for your LinearB organization.
  • The repository you deploy is already connected to LinearB.
  • Your pipeline can access:
    • The repository URL (repo_url), and
    • The Git ref of what you deploy (ref_name – tag or commit SHA).

Estimated effort

  • Adding a POST call in your deploy job typically takes 15–20 minutes.
  • Extra time may be needed to align repo_url, ref_name, and any stage/service naming with your conventions.

Authentication and API tokens

  1. In LinearB, go to Company Settings → API Tokens.
  2. Create (or reuse) an API token for your deployment integration.
  3. Include the token in each request header:
Authorization: Bearer <your_api_token>

1. Create Deployment

From your deployment pipeline, call the Deployment API whenever a deployment occurs.

Endpoint

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

Body parameters

Field Type Required? Description Example
repo_url string Yes HTTPS URL of the Git repository being deployed.
Must match the repository connected in LinearB.
Typically includes a .git suffix.
Pattern (from API spec): ^https://[a-zA-Z0-9./+^@_-]{15,250}$ 		"https://github.com/owner/my-repo.git"
ref_name string Yes

Git ref of the deployed version. Accepts:

  • Commit SHA (short or long)
  • Tag name

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

 "v1.20.55" or "cf8386c6c92bb2..."
timestamp string (ISO 8601) Optional Time the deployment (or pre-deployment stage) occurred.
If omitted, LinearB uses the time the request is received.
Example format: YYYY-MM-DDThh:mm:ssZ 		"2022-03-14T22:23:34Z"
stage string (lowercase) Optional Custom stage key for this deployment (for example, "staging", "preprod", "release").
Default stage for production deployments is typically "release".
Must match the stage keys configured for your organization by LinearB.		 "staging"
services array of strings Optional List of LinearB service names for this deployment. ["billing-service", "auth-service"]
Basic example (minimum required)

Report a deployment using a tag:

{
  "repo_url": "https://github.com/owner/my-repo.git"
  "ref_name": "v1.20.55"
}

Report a deployment using a commit SHA:

{
  "repo_url": "https://github.com/owner/my-repo.git"
  "ref_name": "cf8386c6c92bb24b3e7a48a62cef758d6dbed0ca"

}
Deployment with custom stage
{
  "repo_url": "https://github.com/owner/my-repo.git"
  "ref_name": "cf8386c6c92bb24b3e7a48a62cef758d6dbed0ca"
  "timestamp": "2022-03-14T22:23:34Z"
  "stage": "staging"
}
Deployment with services
{

  "repo_url": "https://github.com/owner/my-repo.git"
  "ref_name": "cf8386c6c92bb24b3e7a48a62cef758d6dbed0ca"
  "timestamp": "2022-03-14T22:23:34Z"
  "stage": "release"
  "services": [
    "billing-service"
    "auth-service"
  ]
}

2. How LinearB Determines Which Branches Were Deployed

Git ancestry logic (core behavior)

After receiving a deployment event, LinearB:

  • Identifies the deployed ref (ref_name – tag or commit).
  • Finds all branches / PRs in the merged state for that repository.
  • For each merged branch, checks whether the branch’s tip commit is an ancestor of the deployed ref using Git logic equivalent to: 
    git merge-base --is-ancestor <branch-tip> <ref_name>
  • If the answer is “yes”, LinearB:
    • Marks the branch/PR as deployed in this deployment.
    • Closes cycle time at the deployment timestamp.
    • Links the branch/PR to that deployment event.

Important: LinearB does not assume all merged branches are deployed. Inclusion is based on Git ancestry, not on when the PR was merged.

Important Timing & ordering considerations

  • The deployed ref is typically newer than the branch commits it contains.
  • A branch can have a merge timestamp that appears later than the deployment time.
  • As long as the branch’s commit is an ancestor of ref_name, LinearB considers it deployed.
  • Each deployment event triggers a fresh evaluation of which branches should be included.

This means deployments are always based on actual Git history, not clock comparisons.

Using Services in LinearB (Optional)

Using services

If you send services in the payload, LinearB:

  • Scopes deployment matching to the specified service(s).
  • Only marks branches as deployed if they touched those services.
  • Applies the same is-ancestor logic, but filtered by service configuration.

If you are using Services with a monorepo, this can prevent unrelated PRs from being counted as deployed when only one microservice is shipped.

Custom Stages through Deployment API (Optional)

Custom stages

Note: Custom stages require configuration by your LinearB team. Please contact your account manager or support before relying on custom stage keys.

You can send deployment events for any stage in your pipeline (for example: "staging", "preprod", "release").

Key behaviors:

  • The same Git ancestry matching is applied at every stage.
  • A branch remains in merged until it reaches its final deployment stage (for example, "release").
  • Stages are processed in a defined order for your organization.
  • You may skip a stage, but you cannot revert back to an earlier stage once a later stage is reported.
  • When a deployment is reported for a given stage, LinearB:
    • Looks at all branches in merged state.
    • Excludes branches already deployed in a later stage.
    • Marks remaining branches as deployed for that stage if they satisfy the ancestry logic.

3. List Deployments

Retrieve deployments recorded in LinearB

Use this endpoint to query deployments you have previously reported.

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

Common query parameters

  • repository_id – filter by LinearB repository ID.
  • before / after – date/time window (ISO 8601).
  • limit – max number of results (1–100, default 10).
  • stage – filter by stage key.
  • commit_sha – filter by commit SHA.
  • sort_by / sort_dir – sorting controls.
  • offset – pagination cursor.

4. Responses

Create deployment responses

200 — Successful Response

{
  "request_id": "string"
}

Common error codes

  • 400 — Bad Request (invalid JSON or missing required fields).
  • 401 — Unauthorized (missing or invalid token).
  • 405 — Method Not Allowed.
  • 422 — Validation Error (field-level issues).
  • 500 — Internal Server Error.
     
List deployments responses

200 — Successful Response

{
  "total": 0
  "items": [
    {
      // deployment objects
    }
  ]
}

Error codes mirror the create endpoint (400, 401, 405, 422, 500).

 

5. Verification & Troubleshooting

Verify a new deployment

  1. Send a test deployment via POST /api/v1/deployments.
  2. Use GET /api/v1/deployments to confirm it was recorded.
  3. In LinearB, verify that the expected merged PRs are now marked as deployed.

Quick fixes (most common issues)

  • Deployment not appearing
    – Confirm repo_url matches a connected repository (including any expected .git suffix).
    – Verify ref_name is a valid tag or commit SHA in that repository.
    – Check your API response for 4xx/5xx errors and validation messages.
  • PRs not marked as deployed
    – Ensure affected branches/PRs are in the merged state.
    – Confirm the PR’s tip commit is in the ancestry of ref_name.
    – If using services, verify service configuration and that the PR touched those services.
  • Validation (422) errors
    – Check that all required fields (repo_url, ref_name) are present.
    – Verify timestamp is a valid ISO 8601 string if provided.
    – Ensure stage and services use the expected formats (lowercase strings).

Advanced troubleshooting (problem → cause → fix)

Use this matrix to diagnose more complex issues.

Problem Cause Fix
Branch not marked as deployed

Git ancestry does not show the branch’s tip commit as an ancestor of the deployed ref. Common causes:

  • Wrong commit/tag was sent as ref_name.
  • A different branch (for example, hotfix) was actually deployed.
 Confirm the commit SHA or tag in the API request exactly matches the deployed version.
If using commits, verify ancestry with:
git merge-base --is-ancestor <branch-tip> <ref_name>.
Too many branches marked as deployed Incorrect ref_name or missing services scoping in a monorepo. If the ref represents a broad deployment, all ancestor branches may be included. Verify that ref_name exactly matches the deployed artifact.
For per-service deployments, include services and ensure your service configuration matches your repo structure.
Deployment assigned to wrong stage Deployment API was called with an incorrect stage key. Re-send the deployment event with the correct stage value.
Confirm valid stage keys with your LinearB team.
Deployment appears but branches do not Branches were not in merged state at evaluation time.
LinearB only evaluates merged branches for inclusion.		 Confirm branches were merged before sending the deployment event.
If merges happen later, re-send the deployment call after merge activity is complete.
Custom stage behavior seems off Stage order or the “no revert” rule is affecting evaluation.
Once a branch is deployed to a later stage, it cannot be moved back to an earlier one.		 Check which stage the deployment was reported to and whether the branch has already been deployed to a later stage.

6. FAQ

Does LinearB use timestamps to decide which branches were deployed?

No. Inclusion is based on Git ancestry (git merge-base --is-ancestor) between the branch tip and ref_name. Timestamps are not used in the decision.

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

If the branch’s commit is an ancestor of the deployed ref, it is still considered included. Git history determines inclusion, not merge time.

Can I deploy only one service in a monorepo?

Yes. Include services in the Deployment API call to limit matching to that service’s changes. This prevents unrelated services in the same repo from being marked as deployed.

Do custom deployment stages change matching behavior?

No. Git ancestry logic is the same for all stages. Stages only affect release progression and visibility (for example, Staging → Pre-Prod → Release).

Do I have to send a timestamp?

No. If you omit timestamp, LinearB uses the time the request is received as the deployment time.

Can I send multiple deployments for the same ref?

Yes. Each API call is treated as a separate deployment event. Use stage and services to distinguish different environments or services.

How do deployments relate to CFR / MTTR?

Deployments provide the foundation for linking incidents (via the Incidents API or incident rules) to specific code changes. When incidents are associated with deployments, LinearB can compute Change Failure Rate (CFR) and Mean Time to Restore (MTTR) using those deployments as anchors.

For additional information, please visit our external API documentation

For additional technical support, please contact LinearB support.

Related articles