Back To Core Concepts

Cartos Release Trigger: Setup & Requirements

Use this when you want CI/CD (GitHub Actions, GitLab, CircleCI, etc.) to notify Cartos about a release so Cartos can start ownership and impact follow-up.

If you need help with where to configure the company-level token in the product, start with Company Settings: Configure Cartos, Integrations, and Webhooks.

If you want a ready-made GitHub Actions integration, use the Cartos Release Trigger action on GitHub Marketplace.

Prefer the reusable workflow for copy-paste setup. Add ANAMAP_COMPANY_ID as a repository variable and ANAMAP_RELEASE_TRIGGER_TOKEN as a repository secret, then call alex-schlee/anamap-release-trigger/.github/workflows/notify-anamap.yml@v1 from your workflow.

Endpoint

  • POST /api/public/cartos-release-trigger

Example full URL:

  • https://your-anamap-domain.com/api/public/cartos-release-trigger

Authentication (required in production)

Cartos validates one of the following token sources:

  1. Company-level release token (configured in Company Settings)
  2. Environment fallback token (AGENT_RELEASE_WEBHOOK_TOKEN or AGENT_EMAIL_WEBHOOK_TOKEN)

Send the token in one of these locations:

  • Header: x-cartos-release-trigger-token: <token> (recommended)
  • Header: Authorization: Bearer <token>
  • Header: x-webhook-token: <token>
  • Query string: ?token=<token>

Where to manage the token in Anamap

If you want a company-specific webhook credential instead of relying only on an environment fallback token:

  1. Open the Company Dashboard for the correct company.
  2. Open Company Settings.
  3. Find the Cartos Release Trigger section.
  4. Paste a new token into Release Webhook Token (set or rotate).
  5. Save the token.

You can also disable the company-level token from that same settings block.

Minimum payload required

  • companyId (UUID) is required

Recommended payload:

{
  "provider": "github-actions",
  "companyId": "<company-uuid>",
  "eventType": "release",
  "eventId": "release-2026-03-01-001",
  "releaseName": "Checkout Funnel Update",
  "description": "Improved checkout UX and instrumentation updates.",
  "tags": ["checkout", "funnel"],
  "changeType": "new_feature",
  "version": "v2.4.0",
  "environment": "prod"
}

Fastest GitHub setup: reusable workflow

The reusable workflow is a prebuilt workflow job hosted at alex-schlee/anamap-release-trigger/.github/workflows/notify-anamap.yml@v1.

Use it when you want the fastest setup and a sane default integration.

What you need to configure first:

  • Repository variable: ANAMAP_COMPANY_ID
  • Repository secret: ANAMAP_RELEASE_TRIGGER_TOKEN

What this gives you:

  • You do not need to remember the low-level action inputs.
  • You do not need to add checkout or fetch-depth: 0 yourself.
  • You get a maintained wrapper that already calls the underlying action correctly.

Copy-paste example:

name: Deploy and Notify Anamap

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  notify-anamap:
    uses: alex-schlee/anamap-release-trigger/.github/workflows/notify-anamap.yml@v1
    with:
      company-id: ${{ vars.ANAMAP_COMPANY_ID }}
      environment: prod
      change-type: new_feature
    secrets:
      trigger-token: ${{ secrets.ANAMAP_RELEASE_TRIGGER_TOKEN }}

More realistic after-deploy example:

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy app
        run: ./deploy.sh

  notify-anamap:
    needs: deploy
    if: ${{ success() }}
    uses: alex-schlee/anamap-release-trigger/.github/workflows/notify-anamap.yml@v1
    with:
      company-id: ${{ vars.ANAMAP_COMPANY_ID }}
      environment: prod
      change-type: new_feature
    secrets:
      trigger-token: ${{ secrets.ANAMAP_RELEASE_TRIGGER_TOKEN }}

When to use the action directly instead

Use the action directly if you want full control inside an existing job or need unusual wiring.

Direct-action example:

name: Deploy and Notify Anamap

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Deploy app
        run: ./deploy.sh

      - name: Notify Anamap
        if: success()
        uses: alex-schlee/anamap-release-trigger@v1
        with:
          company-id: ${{ vars.ANAMAP_COMPANY_ID }}
          trigger-token: ${{ secrets.ANAMAP_RELEASE_TRIGGER_TOKEN }}
          environment: prod

If you are choosing between the two:

  • Use the reusable workflow when you want the fastest setup and a sane default integration.
  • Use the action directly if you want full control inside an existing job or need unusual wiring.

The streamlined setup you would want is effectively one pasted job. Outside org-scoped templates, the reusable workflow is the closest GitHub-native version of that model.

Success and duplicate behavior

  • 202: accepted, Cartos created follow-up question and scheduled deferred release validation
  • 401: token invalid/missing
  • 409: duplicate webhook event (same provider + webhook ID)

Local verification

You can validate end-to-end with:

  • npm run -s test:agent-release-webhook -- --replay --company-id <uuid> --token <token>

Optional flags:

  • --url <webhook-url>
  • --type release|pr|deployment
  • --event-id <stable-id>

What Cartos does after receipt

  • Creates a high-priority ownership/impact question
  • Schedules the first off-cycle validation 25 hours after webhook receipt for all connected data sources
  • Runs that deferred validation outside the company's normal Cartos cadence once the delay window expires

For the broader operating model around recipients, follow-up, and channel behavior, see How Cartos Operates: What to Expect as a Team and Interacting with Cartos: Chat, Email, Slack, and Better Context.