Scripts and CI

The assent command lets a script or CI job ask you before a risky step and wait for your answer, check your standing rules, and report each run. It reads its agent key from the environment, so it never needs an interactive login.

Set it upCopy Anchor Link

1. In Assent, open Agents, choose Add agent, name it after the job (for example Release pipeline) and copy its agent key. It starts with oak_ and is shown once.
2. Store the key as a secret in your CI, named ASSENT_AGENT_KEY. On your own computer, export it or save it in ~/.assent/config.json (see Command line).
3. Install the command line. It needs Node.js 20 or later.

npm install -g assent-cli

4. Check the key:

assent whoami

It prints one line of JSON describing the agent. Exit code 5 means the key is missing or wrong.

Ask before a risky stepCopy Anchor Link

assent ask \
  --title "Deploy build 512 to production?" \
  --why "All checks passed on the release branch" \
  --rule-action deploy:web --target production \
  --dedupe deploy:web:512 \
  --wait --timeout 1800

• --wait checks every 15 seconds until you answer, for at most --timeout seconds (default 3600). When you answer, it marks the answer as picked up and prints the ask with its answer.
• An approval comes back with answer.actionId done; a decline with decline. Act only on done.
• --rule-action and --target let you answer Always or Never, so the next matching ask is answered for you.
• --dedupe makes a retried job reuse the same ask instead of sending a second one.

Exit codes for ask --wait:

Treat anything other than an answer of done as "do not go ahead".

GitHub ActionsCopy Anchor Link

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Ask before deploying
        env:
          ASSENT_AGENT_KEY: ${{ secrets.ASSENT_AGENT_KEY }}
        run: |
          ACTION=$(npx --yes assent-cli@latest ask \
            --title "Deploy ${GITHUB_SHA::7} to production?" \
            --why "The release workflow passed on ${GITHUB_REF_NAME}" \
            --rule-action deploy:web --target production \
            --dedupe "deploy:web:${GITHUB_SHA}" \
            --wait --timeout 1800 --get answer | jq -r '.actionId // empty')
          test "$ACTION" = "done"
      - run: ./deploy.sh

npx runs the latest assent-cli without a global install. --get answer prints just the answer object. If you decline, or the ask times out (exit 6) or expires (exit 3), ACTION is not done, so test fails the step and the deploy never runs.

Windows and PowerShellCopy Anchor Link

The commands are the same on Windows. Set the key with $env:ASSENT_AGENT_KEY = "oak_...", and check the exit code with $LASTEXITCODE:

$answer = assent ask --title "Run the clean-up job?" --why "It deletes builds older than 30 days" --wait --timeout 900 --get answer | ConvertFrom-Json
if ($LASTEXITCODE -ne 0 -or $answer.actionId -ne "done") { exit 1 }

If PowerShell refuses to run assent.ps1 because running scripts is disabled, call assent.cmd instead.

Check your rules firstCopy Anchor Link

When the action might already be covered by one of your standing rules, check before asking:

assent rules check --action deploy:web --target production

Exit 0 means a rule allows it, 10 means a rule forbids it, and 11 means no rule covers it, so ask. See Rules.

Report each runCopy Anchor Link

Scheduled jobs can show up in Runs with how they ended:

RUN=$(assent run start --summary "Nightly clean-up" --get uuid)
./clean-up.sh > clean-up.log 2>&1
assent run finish "$RUN" --exit-code $? --summary "Nightly clean-up" --log-file clean-up.log

run finish redacts emails, keys, tokens, phone numbers and home paths from the summary and log tail before sending.

Keep two jobs apartCopy Anchor Link

assent lock acquire deploy:web --ttl 45 --wait 90 && ./deploy.sh; assent lock release deploy:web

If another agent holds the lock after 90 seconds, lock acquire exits with 3 and the deploy does not start.

When Assent is unreachableCopy Anchor Link

Decide what a job should do if Assent cannot be reached (exit 69). For a risky step, stop: never treat "no answer" as approval. For reporting commands such as run start and run finish, carry on with the job.

Command line lists every command, option, setting and exit code.