Skip to content
Hexel StudioDocs

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.

On this page

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.

.github/workflows/harness.yml
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:

VariableValue
HEXEL_WEB_IDENTITY_TOKEN_FILEA file holding the job's OIDC token, issued for the audience https://sts.hexelstudio.com/workload
HEXEL_ROLEThe role's id, role_...
HEXEL_ROLE_SESSION_NAMEOptional. 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:

.github/workflows/harness.yml
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 2

In 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.