> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Report a deployment

> Report a deployment from the pipeline once it finishes, passing the deployed SHA, the repository, the environment and the service. The organization and the repository must have post-deploy verification enabled, and `service` must name one of the services configured for it. Gitar records the deployment and checks production logs for every pull request it shipped 15 minutes, 30 minutes, 1 hour, 1 day and 3 days after `deployed_at`.

Gitar measures each deployment from the previous one it recorded for the same repository, environment and service, so the pipeline does not need to know what was deployed before. The first deployment to an environment only checks the pull request that landed as `sha`. Pass `base_sha` to measure from a specific commit instead.

One deployment verifies at most 100 pull requests. Without `base_sha`, a larger range or one Gitar cannot resolve verifies the newest 100 merged since the previous deployment and up to `sha`, skipping any an earlier deployment in the stream shipped. With `base_sha`, the same cases return `400`.

SHAs may be full or abbreviated to at least 7 hex characters. Reporting the latest deployment's SHA again is treated as a retry and returns the same deployment.

The repository is resolved within the token's organization, so one the token cannot see returns `404`.

A `202` confirms the deployment was recorded and its pull requests are scheduled for verification. It does not mean monitoring has started, and `queued` is empty when the deployment shipped no reviewed pull request.

Preview

> [!NOTE]
>
> This endpoint is part of [Post-Deploy Verifications](https://docs.gitar.ai/features/post-deploy-verifications.md), in preview for select pilot organizations. Other organizations receive `403`.

Report each successful deployment from the pipeline. Gitar identifies the PRs it shipped and checks their production logs on the [check schedule](https://docs.gitar.ai/features/post-deploy-verifications.md#check-schedule).

## Prerequisites

| Requirement | Setup |
| - | - |
| CloudWatch connection tagged with the `environment`, or a single untagged connection | [Connect Amazon CloudWatch](https://docs.gitar.ai/features/post-deploy-verifications/setup.md#1-connect-amazon-cloudwatch) |
| Repository with verification on and the `service` configured | [Map services to log groups](https://docs.gitar.ai/features/post-deploy-verifications/setup.md#2-map-services-to-log-groups) |
| API key | Create one under **Settings -> API Keys**. Keys created in the dashboard include the required `tracks:write` scope. |

## Example

```bash theme={null}
curl -X POST https://api.gitar.ai/v1/external/deployments \
  -H "Authorization: Bearer $GITAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sha": "4d81e07a",
    "repo_owner": "acme",
    "repo_name": "worker",
    "environment": "production",
    "service": "worker"
  }'
```

```json theme={null}
{
  "deployment_id": "0193f4c2-8a1e-7c3b-9f2d-4e5a6b7c8d9e",
  "range_source": "compare",
  "queued": [
    {
      "deployment_id": "0193f4c2-8a1e-7c3b-9f2d-4e5a6b7c8d9e",
      "plan_execution_id": "0193f2a7-1b2c-7d3e-8f4a-5b6c7d8e9f0a",
      "pr_url": "https://github.com/acme/worker/pull/482"
    }
  ]
}
```

## Repository owner and name

Set `repo_owner` and `repo_name` using the code host's identifiers:

| Code host | `repo_owner` | `repo_name` |
| - | - | - |
| GitHub | Organization or user | Repository |
| GitLab | Full namespace path, including subgroups | Project path |
| Bitbucket Cloud | Workspace slug | Repository slug |
| Bitbucket Data Center | Project key | Repository slug |
| Azure DevOps | Organization | Repository |
| AWS CodeCommit | 12-digit AWS account ID | Repository |

For example, the GitLab project `gitlab.com/acme/platform/worker` has `repo_owner` `acme/platform` and `repo_name` `worker`.

See the setup guide for [GitHub Actions](https://docs.gitar.ai/features/post-deploy-verifications/setup.md#github-actions) and [GitLab CI](https://docs.gitar.ai/features/post-deploy-verifications/setup.md#gitlab-ci) examples.

## Errors

| Status | Cause |
| - | - |
| `400` | Invalid field or unknown commit. Also returned when `service` is not configured, no CloudWatch connection serves `environment`, or the service has no log groups for that environment. The response identifies the cause. |
| `403` | The organization is not in the preview, or the key lacks `tracks:write`. |
| `404` | The repository is not connected to the key's organization. |
| `409` | Verification is turned off for the repository. |

Retrying with the same `sha` as the latest deployment in the stream returns that deployment rather than recording a new one, so a pipeline can retry safely.


## OpenAPI

````yaml post /external/deployments
openapi: 3.1.0
info:
  title: Gitar External API
  description: API for managing your Gitar installation and integrations
  contact:
    name: Gitar
    url: https://gitar.ai
    email: noreply@gitar.ai
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.gitar.ai/v1
security: []
paths:
  /external/deployments:
    post:
      tags:
        - Deployments
      summary: Report a deployment
      description: >-
        Report a deployment from the pipeline once it finishes, passing the
        deployed SHA, the repository, the environment and the service. The
        organization and the repository must have post-deploy verification
        enabled, and `service` must name one of the services configured for it.
        Gitar records the deployment and checks production logs for every pull
        request it shipped 15 minutes, 30 minutes, 1 hour, 1 day and 3 days
        after `deployed_at`.


        Gitar measures each deployment from the previous one it recorded for the
        same repository, environment and service, so the pipeline does not need
        to know what was deployed before. The first deployment to an environment
        only checks the pull request that landed as `sha`. Pass `base_sha` to
        measure from a specific commit instead.


        One deployment verifies at most 100 pull requests. Without `base_sha`, a
        larger range or one Gitar cannot resolve verifies the newest 100 merged
        since the previous deployment and up to `sha`, skipping any an earlier
        deployment in the stream shipped. With `base_sha`, the same cases return
        `400`.


        SHAs may be full or abbreviated to at least 7 hex characters. Reporting
        the latest deployment's SHA again is treated as a retry and returns the
        same deployment.


        The repository is resolved within the token's organization, so one the
        token cannot see returns `404`.


        A `202` confirms the deployment was recorded and its pull requests are
        scheduled for verification. It does not mean monitoring has started, and
        `queued` is empty when the deployment shipped no reviewed pull request.
      operationId: createDeployment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeploymentRequest'
        required: true
      responses:
        '202':
          description: Deployment recorded and its pull requests queued for verification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '400':
          description: Invalid request or unknown commit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseFailure'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseFailure'
        '403':
          description: >-
            Insufficient scopes, or post-deploy verification is not enabled for
            the organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseFailure'
        '404':
          description: Repository not found in the token's organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseFailure'
        '409':
          description: Post-deploy verification is not enabled for the repository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseFailure'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateDeploymentRequest:
      type: object
      description: One deployment of one repository to one environment.
      required:
        - sha
        - repo_owner
        - repo_name
        - environment
        - service
      properties:
        base_sha:
          type:
            - string
            - 'null'
          description: |-
            Measure from this commit rather than the previous deployment Gitar
            recorded.
          example: 9f2c1ab
        deployed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the deployment went out, RFC 3339 with an offset. Defaults to
            the

            time of this call.
          example: '2026-01-01T12:00:00Z'
        environment:
          type: string
          description: >-
            Environment the deployment went to. Each environment keeps its own
            history.
          example: production
        repo_name:
          type: string
          description: >-
            Repository name on the code host. On GitLab this is the project
            path, and on Bitbucket

            the repository slug.
          example: worker
        repo_owner:
          type: string
          description: >-
            Repository owner on the code host: the GitHub organization or user,
            the full GitLab

            namespace path including subgroups, the Bitbucket Cloud workspace
            slug, the Bitbucket

            Data Center project key, the Azure DevOps organization, or the
            CodeCommit AWS account ID.
          example: acme
        service:
          type: string
          description: >-
            Service that was deployed, one of those configured in the
            repository's

            post-deploy settings. Each service keeps its own history, and only
            pull

            requests Gitar tagged with it are verified.
          example: worker
        sha:
          type: string
          description: Commit that was deployed.
          example: 4d81e07
    Deployment:
      type: object
      description: A recorded deployment and the pull requests it will verify.
      required:
        - deployment_id
        - range_source
        - queued
      properties:
        deployment_id:
          type: string
        queued:
          type: array
          items:
            $ref: '#/components/schemas/QueuedPullRequest'
        range_source:
          $ref: '#/components/schemas/RangeSource'
    ResponseFailure:
      type: object
      required:
        - message
      properties:
        error_code:
          type:
            - string
            - 'null'
        message:
          type: string
    QueuedPullRequest:
      type: object
      description: One pull request queued for verification.
      required:
        - plan_execution_id
        - pr_url
        - deployment_id
      properties:
        deployment_id:
          type: string
          description: Deployment the verification checks.
        plan_execution_id:
          type: string
          description: >-
            Plan execution that reviewed the pull request, which the
            verification run

            hangs off.
        pr_url:
          type: string
          description: Pull request URL as Gitar recorded it.
    RangeSource:
      type: string
      description: How a deploy's pull requests were worked out.
      enum:
        - baseline
        - compare
        - merged_at_window
        - override
        - explicit
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.