Run from CI
Apply agents and create tasks from a CI job, with a service user's API key or with the job's own identity and no stored secret.
A CI job can apply your agents from files, create tasks and wait for them. It signs in as a program, not a person, in one of two ways.
With a service user's API key
Create a service user, attach a policy with only the harness actions the job needs (for example harness:task:create and harness:task:read, see Permissions), and store its API key as a CI secret. The CLI and the SDKs read HEXEL_API_KEY and exchange it for an access token on each run.
jobs:
audit:
runs-on: ubuntu-latest
env:
HEXEL_API_KEY: ${{ secrets.HEXEL_API_KEY }}
HEXEL_ORG: org_123
HEXEL_WORKSPACE: ws_456
HEXEL_ENV: env_789
steps:
- uses: actions/checkout@v4
- name: Install hexel
run: |
curl -fsSL https://hexelstudio.com/install.sh | HEXEL_INSTALL_DIR="$HOME/.local/bin" sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- run: hexel harness apply -f harness/
- run: hexel harness task create "Audit this commit" --agent auditor@prod --budget-usd 2 --follow--follow exits when the task ends. A task created by a service user belongs to it.
With workload identity
With workload identity, the job exchanges its own OIDC token at Hexel Studio's token service for a session of a role, so no Hexel Studio secret is stored in CI. Register your CI's issuer as a workload identity provider whose audiences list https://sts.hexelstudio.com/workload. The role's trust policy names that provider and the workloads it trusts, for example one repository's main branch (Workload identity, Roles). Give the role only the harness actions the job needs.
The CLI and the SDKs use these variables:
| Variable | Value |
|---|---|
HEXEL_WEB_IDENTITY_TOKEN_FILE | A file holding the job's OIDC token, issued for the audience https://sts.hexelstudio.com/workload |
HEXEL_ROLE | The role's id, role_... |
HEXEL_ROLE_SESSION_NAME | Optional. A name for the session, for example the CI run's id |
In GitHub Actions, the job needs permissions: id-token: write. GitHub's OIDC tokens last about five minutes and the CLI exchanges the file on every command, so write a fresh token to the file before each hexel command:
permissions:
contents: read
id-token: write
jobs:
audit:
runs-on: ubuntu-latest
env:
HEXEL_ORG: org_123
HEXEL_WORKSPACE: ws_456
HEXEL_ENV: env_789
HEXEL_ROLE: role_123
HEXEL_ROLE_SESSION_NAME: gha-${{ github.run_id }}
HEXEL_WEB_IDENTITY_TOKEN_FILE: ${{ github.workspace }}/.hexel-oidc-token
steps:
- name: Install hexel
run: |
curl -fsSL https://hexelstudio.com/install.sh | HEXEL_INSTALL_DIR="$HOME/.local/bin" sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Create a task
run: |
umask 077
curl -fsS -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https%3A%2F%2Fsts.hexelstudio.com%2Fworkload" \
| jq -r .value > "$HEXEL_WEB_IDENTITY_TOKEN_FILE"
hexel harness task create "Audit this commit" --agent auditor@prod --budget-usd 2In the SDKs, defaultCredentials() (TypeScript) and the Python client's default credential chain pick up the same variables. The token's organization, the role's, must match HEXEL_ORG when you set it.