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

# Set up post-deploy verifications

> Configure CloudWatch access and report deployments from a pipeline

Preview

> [!NOTE]
>
> Post-Deploy Verifications are in preview for select pilot organizations and read Amazon CloudWatch Logs only.

The organization admin role is required to configure CloudWatch and repository services, and to create an API key for the pipeline.

## 1. Connect Amazon CloudWatch

Open **Settings -> Integrations** and select **Configure** on the **Amazon CloudWatch** card under **Observability**.

Amazon CloudWatch card under Observability on the integrations page

**1. Add a connection**

Select **Add AWS connection** and enter the account ID and region.

Under **Environments**, enter the deployment environments this account serves, for example `production`. Match the `environment` the pipeline reports.

**2. Create the IAM role**

Select **Set up and validate** on the connection. In the AWS account, create the IAM role named in the dialog, `gitar-cloudwatch-mcp-<region>`.

Choose **Custom trust policy** and paste the **Role trust policy** from the dialog. The policy permits Gitar to assume the role only with the organization's external ID.

**3. Attach the permissions policy**

Add an inline policy named `GitarCloudWatchRead` with the **CloudWatch permissions policy** from the dialog.

The policy grants read-only access to CloudWatch Logs Insights queries, log group listing and log anomalies in this account and region.

Narrow the log group ARNs to limit access.

**4. Validate access**

Select **Validate access**. Gitar checks role assumption, log group listing and access to the log groups configured for repositories using this connection.

### Accounts, regions and environments

Each connection covers one AWS account and region. To read from another account or region, add another connection.

The environment of a deployment decides which connection Gitar reads through, so staging and production can live in different accounts. With more than one connection, each must be tagged, and an environment can be tagged on only one connection.

## 2. Map services to log groups

Open **Settings -> Configuration** and open the post-deploy verification settings for a repository, then turn on **Verify deployments**. A repository can only be turned on once the organization has a CloudWatch connection.

Verify deployments turned on for a repository, with services and their log groups

Add a service for each deployable unit the repository builds, such as `api` or `worker`.

| Field | Purpose |
| - | - |
| **Service name** | The name the pipeline reports as `service`. |
| **Description** | What the service runs and which paths build into it. Gitar uses this to tag PRs with the services they affect. |
| **Log groups** | The CloudWatch log groups the service writes to. Browse a connection to pick them by name. |

Each log group applies to every environment by default. Limit it to specific environments only when its name differs between accounts, for example `/ecs/api-staging` and `/ecs/api-production`.

Service and environment names may contain letters, digits, `.`, `_`, `-` and `/`, up to 64 characters.

Plans start with the next full review after verification is enabled. PRs without a plan are not verified.

## 3. Report deployments

Open **Settings -> API Keys** and select **Create API key**. Store the key as a secret in the deployment system, for example `GITAR_API_KEY`. See [Creating an API token](https://docs.gitar.ai/api-reference/overview.md#creating-an-api-token) for details.

### Deployment request

After each successful deployment from the default branch, send one [Create deployment](https://docs.gitar.ai/api-reference/deployments/create-deployment.md) request per service. Each deployment becomes the baseline for the next one in its [stream](https://docs.gitar.ai/features/post-deploy-verifications.md#deployment-streams).

Set `service` to the configured service name and `environment` to the matching connection tag. The API reference defines [repository owner and name](https://docs.gitar.ai/api-reference/deployments/create-deployment.md#repository-owner-and-name) for each code host and the optional `deployed_at` timestamp.

```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"
  }'
```

A `202` response confirms the deployment was recorded and lists the PRs scheduled for verification. Results appear in **Observability** from the first [checkpoint](https://docs.gitar.ai/features/post-deploy-verifications.md#check-schedule), 15 minutes after deployment.

### GitHub Actions

Add a step after the deployment step of a workflow that deploys from the default branch:

```yaml theme={null}
- name: Report deployment to Gitar
  if: success() && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
  env:
    GITAR_API_KEY: ${{ secrets.GITAR_API_KEY }}
    REPO_OWNER: ${{ github.repository_owner }}
    REPO_NAME: ${{ github.event.repository.name }}
  run: |
    jq -n \
      --arg sha "$GITHUB_SHA" \
      --arg owner "$REPO_OWNER" \
      --arg name "$REPO_NAME" \
      '{sha: $sha, repo_owner: $owner, repo_name: $name, environment: "production", service: "worker"}' \
    | curl -sf -X POST https://api.gitar.ai/v1/external/deployments \
        -H "Authorization: Bearer $GITAR_API_KEY" \
        -H "Content-Type: application/json" \
        -d @-
```

### GitLab CI

Add a job after the deployment job of a pipeline that deploys from the default branch. Store the API key as a masked CI/CD variable named `GITAR_API_KEY`.

```yaml theme={null}
report-deployment:
  stage: .post
  image: alpine:latest
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: on_success
  script:
    - apk add --no-cache curl jq
    - |
      jq -n \
        --arg sha "$CI_COMMIT_SHA" \
        --arg owner "$CI_PROJECT_NAMESPACE" \
        --arg name "$CI_PROJECT_NAME" \
        '{sha: $sha, repo_owner: $owner, repo_name: $name, environment: "production", service: "worker"}' \
      | curl -sf -X POST https://api.gitar.ai/v1/external/deployments \
          -H "Authorization: Bearer $GITAR_API_KEY" \
          -H "Content-Type: application/json" \
          -d @-
```

`CI_PROJECT_NAMESPACE` supplies the full namespace path and `CI_PROJECT_NAME` supplies the project path.

For a pipeline that deploys several services, add one step or job per service, or loop over them.


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