API - Deployment

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.

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.

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

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

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

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>

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"

          }

{

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

            "ref_name": "cf8386c6c92bb24b3e7a48a62cef758d6dbed0ca"

            "timestamp": "2022-03-14T22:23:34Z"

            "stage": "staging"

          }

{

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

            ]

          }

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.

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

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.

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.

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

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.

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.

200 — Successful Response

{

            "total": 0

            "items": [

              {

                // deployment objects

              }

            ]

          }

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

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.

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

Use this matrix to diagnose more complex issues.

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.

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

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.

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

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

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

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.