Declare from your CI

monocle deploy declares a deployment from your CI. It detects the version, the commit, the author, and the CI run, then calls the Deployments API.

Set up

Create a deploy key and store it as the MONOCLE_API_KEY secret of your CI.
Install the CLI:
Terminal
```
npm install -D @monocle.sh/cli
```
Run monocle deploy at the end of your deployment job:
Terminal
```
monocle deploy --service api --environment production
```

The environment slug must already exist in Monocle. To check the payload first, add --dry-run. It prints each field and where its value came from, and needs no API key.

Record the start and the end

Call the command twice, with a different status:

Terminal

monocle deploy --service api --environment production --status started
# ... deploy ...
monocle deploy --service api --environment production --status succeeded

Both calls share an identifier derived from the CI run, so they update the same deployment. On GitHub Actions, the identifier includes the repository, the run ID, the run attempt, the service, and the environment. A rerun is a new deployment.

On GitLab CI and Buildkite, the identifier includes the job ID: send both calls from the same job. CircleCI uses the workflow ID, and Bitbucket Pipelines uses the pipeline UUID and the step run number. If the two calls run in jobs with different identifiers, pass the same --external-id to both.

GitHub Actions example

This workflow declares the start of the deployment, then its success or failure. It assumes your repository installs @monocle.sh/cli and has a deploy npm script.

.github/workflows/deploy.yml

name: Deploy
on:
  workflow_dispatch:
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MONOCLE_API_KEY: ${{ secrets.MONOCLE_API_KEY }}
      MONOCLE_ENVIRONMENT: production
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx --no-install monocle deploy --service api --status started
      - id: rollout
        run: npm run deploy
      - if: ${{ success() }}
        run: npx --no-install monocle deploy --service api --status succeeded
      - if: ${{ failure() && steps.rollout.outcome == 'failure' }}
        run: npx --no-install monocle deploy --service api --status failed

Options

Option	Default
`--service <name>`	Required. The `service.name` of the service.
`--environment <slug>`	`MONOCLE_ENVIRONMENT`. Required if the variable is not set.
`--version <version>`	`MONOCLE_VERSION`. Without it, the CLI sends only the detected commit.
`--commit <sha>`	The commit from the CI variables or the local `.git` directory
`--status <status>`	`succeeded`. Also accepts `started`, `failed`, and `canceled`.
`--started-at <timestamp>`	None. ISO 8601 with a timezone.
`--finished-at <timestamp>`	None. For `succeeded`, Monocle uses the time it receives the request.
`--external-id <id>`	Derived from the CI run. Outside CI, a new identifier for each call.
`--actor <actor>`	The CI user who started the run
`--ci-url <url>`	The URL of the CI run
`--api-key <key>`	`MONOCLE_API_KEY`
`--url <url>`	`https://api.monocle.sh`
`--strict`	Off. Exit with code `1` when the declaration fails.
`--dry-run`	Off. Print the payload and the source of each field without sending it.

The CLI reads its defaults from GitHub Actions, GitLab CI, CircleCI, Buildkite, and Bitbucket Pipelines. Flags override detected values.

A detected commit is sent as commitSha only, not as version. Monocle then matches it with the release that reported this commit in its telemetry.

Exit codes

monocle deploy never fails your pipeline by default. A missing API key, a version or commit it can't detect, and a failed request print a warning and exit with code 0. With --strict, they exit with code 1.

Usage errors always exit with code 1. They include a missing service or environment, an invalid status or timestamp, and an empty flag.

Each request times out after 5 seconds. The CLI retries once after a network error, a timeout, or a 5xx response.

Set up

Record the start and the end

GitHub Actions example

Options

Exit codes

Search documentation