CI with cloakctl

A CI token lets a CI job use your team’s mock and rule sets and upload what it recorded to the team library, without a person’s Mac. cloakctl decrypts the sets on the runner with keys the token carries, so CI gets the same end-to-end encryption as everyone else.

Create a CI token

CI tokens carry team keys, so they’re created in Cloak Proxy on an admin’s Mac, not in the console.

1. On an admin’s Mac, open Settings › Team › CI and click New Token….

2. Enter a label, such as github-actions-web, choose the spaces CI may read (mock sets, rule sets and workspaces), and choose whether it may upload recordings to an open library space. Uploading gives the token no read access to the library. Each set shows who made it and its id. If two sets share a name, confirm which one the token should read.

3. Copy the token. It starts with cct1_ and is shown once, with a GitHub Actions snippet and, for a token that uploads, the library’s ID. Subcloak never sees the token’s keys.

4. Store it as a secret in your CI system, for example a GitHub Actions repository secret.

cloakctl team ci create does the same from Terminal on an admin’s Mac.

Treat a token like a key

Anyone with the token can use it until you revoke it. A CI token can read only rule sets, mock sets and workspaces an admin gives it. It can never read the vault, the library, findings or agents, and it can upload only to an open library, named by its id (--library <id>). It can’t change the team. Make one token per pipeline so you can revoke one without the others.

Use it in a job

Terminal

cloakctl run --team-mocks "Staging mocks" --team-rules "CI rules" \
  --record run.cloaksession --upload --library 9c41… --tag "pr-123" -- npm test

--library takes the 32-character id of the library space the token may upload to, as the New Token sheet shows it (Library ID). A token doesn’t read the library it uploads to, so cloakctl can’t look it up by name.

Name each set by its id, as the New Token sheet’s snippet does (--team-mocks 3f2a…): two spaces can share a name, an id can’t. A name works only while one set the token reads has it; when two do, the run stops and lists their ids. A token reads only the sets an admin gave it: a member who lists the token on a set of their own doesn’t get it applied.

What CI applies from a set

In CI, rules and mock sets (scripts, Map Local, Map Remote, DNS, rewrites, mocks, block and allow rules, breakpoints, alerts and the like) apply only when a manager of that same set approved their current content; others are left out and listed when the run starts. A manager approves them in Held Items… in the app.

cloakctl run checks the team’s signed member list from the token, opens the sets the token was granted, applies them, runs your command through the proxy and, with --upload, uploads the recording to the team library. The library entry records pass or fail, the exit code and, when they’re set, GITHUB_SHA, the branch and the run’s URL.

Command	What it does
cloakctl run --team-mocks ID --team-rules ID … -- COMMAND	Runs COMMAND with those team sets applied (an id, or a name only one set has). Add --record FILE --upload --library ID --tag TAG to upload the recording.
cloakctl team pull --space ID --out DIR	Exports a set the token can read into a folder.
cloakctl team whoami	Shows the token’s team id, its CI member id and the sets it can read. The label is shown in the console and in Settings › Team › CI. Libraries the token only uploads to aren’t listed.

The other cloakctl run options work as usual.

Example: GitHub Actions

This workflow runs on a self-hosted macOS runner with Cloak Proxy 0.7.0 or later installed, as in Headless and CI. The token is in the repository secret CLOAK_TEAM_TOKEN, and the upload library’s id in the repository variable CLOAK_TEAM_LIBRARY.

.github/workflows/api-tests.yml

name: API tests with team mocks
on: [pull_request]

jobs:
  test:
    runs-on: [self-hosted, macOS]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - name: Test against the team's staging mocks
        env:
          CLOAK_TEAM_TOKEN: ${{ secrets.CLOAK_TEAM_TOKEN }}
          CLOAK_TEAM_LIBRARY: ${{ vars.CLOAK_TEAM_LIBRARY }}
        run: |
          cloakctl run --team-mocks "Staging mocks" --team-rules "CI rules" \
            --record run.cloaksession --upload --library "$CLOAK_TEAM_LIBRARY" \
            --tag "pr-${{ github.event.number }}" -- npm test

Where results go

Recordings appear in the team library with a CI mark. They’re kept for 30 days unless someone chooses Keep, which saves it as a normal entry.

Limit (per team)	Value
CI tokens	20
Runs	300 a month for each seat
Recording size	100 MB
Recordings kept	30 days, unless kept

Rename or revoke a token

The console’s CI page lists tokens with their label, how many spaces they can read (names are only in the app), whether they upload, who created them, when they were last used and their runs this month. Owners and admins can Rename or Revoke a token there, and an admin can also Revoke it in Settings › Team › CI on a Mac.

Revoking cuts the token off at Subcloak’s server at once. The next time an admin’s Mac is online, it removes the token from the team and changes the keys, so the token’s keys open nothing written afterwards.

Related

Headless and CIEvery cloakctl run option and exit code.

cloakctlThe full command reference.

Library and FindingsWhere recordings land.

PoliciesBlock CI tokens for the whole team.