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

# Use Tolmo in CI/CD

> Install Tolmo, authenticate with an API key, start a pentest after each deploy, and gate pipelines on findings in GitHub Actions or GitLab CI.

Use your pipeline to keep testing in step with production. Start a Red team agent run after a deploy, and fail a build when critical findings are open.

Use an organization API key to run Tolmo without browser login. Create the key in **Settings → API keys**, then store it as `TOLMO_API_TOKEN` in your CI provider's secret store. Set `TOLMO_ORG_SLUG` to your organization slug.

## GitHub Actions

This workflow installs the CLI into a known directory and prints open critical findings:

```yaml .github/workflows/security.yml theme={null}
name: Review security findings
on: [push, workflow_dispatch]
jobs:
  tolmo-check:
    runs-on: ubuntu-latest
    steps:
      - name: Install Tolmo
        run: |
          curl -fsSL https://tolmo.com/install.sh | TOLMO_INSTALL_DIR="$HOME/.local/bin" sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: List critical findings
        env:
          TOLMO_API_TOKEN: ${{ secrets.TOLMO_API_TOKEN }}
          TOLMO_ORG_SLUG: ${{ secrets.TOLMO_ORG_SLUG }}
        run: tolmo findings list --status open --severity critical --json
```

Listing findings exits successfully even when findings exist. To fail the job when the filtered list is non-empty, replace the last `run` value with:

```yaml theme={null}
run: |
  tolmo findings list --status open --severity critical --json > findings.json
  jq -e 'length == 0' findings.json
```

The CLI collects all matching pages before returning the array. The gate requires `jq` on the runner.

### Start a pentest after each deploy

Production changes on every deploy. Start a Red team agent run when a deploy finishes, so the agent tests what you just shipped instead of waiting for the next scheduled run:

```yaml .github/workflows/pentest-after-deploy.yml theme={null}
name: Pentest after deploy
on:
  workflow_run:
    workflows: [Deploy]
    types: [completed]
jobs:
  red-agent-run:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - name: Install Tolmo
        run: |
          curl -fsSL https://tolmo.com/install.sh | TOLMO_INSTALL_DIR="$HOME/.local/bin" sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Start a Red team agent run
        env:
          TOLMO_API_TOKEN: ${{ secrets.TOLMO_API_TOKEN }}
          TOLMO_ORG_SLUG: ${{ secrets.TOLMO_ORG_SLUG }}
        run: tolmo red-agent run --json
```

The run tests every authorized domain and runs in addition to your schedule. Results arrive through your [notifications](https://docs.tolmo.com/agents/notifications.md) like any other run. See [`tolmo red-agent`](https://docs.tolmo.com/cli/commands/red-agent) for the full command.

## GitLab CI

Store the API key and organization slug in **Settings → CI/CD → Variables**. Mark the API key as masked.

```yaml .gitlab-ci.yml theme={null}
security-check:
  image: ubuntu:24.04
  before_script:
    - apt-get update && apt-get install -y ca-certificates curl tar
    - curl -fsSL https://tolmo.com/install.sh | TOLMO_INSTALL_DIR="$HOME/.local/bin" sh
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - tolmo findings list --status open --severity critical --json
```

## Configuration

`TOLMO_API_TOKEN` bypasses saved profiles. Set `TOLMO_API_URL` if you need an API URL other than `https://api.tolmo.com`. See [Environment variables](https://docs.tolmo.com/cli/environment-variables.md) for precedence.

API keys can read published findings, create drafts, start Red team agent runs, and change the Red team agent schedule. User-only operations, including evidence attachments, require a user token and are not available with an organization API key.


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