---
title: Run from CI
description: 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.
url: https://hexelstudio.com/docs/harness/ci
---

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](https://hexelstudio.com/docs/identity/service-users), attach a policy with only the harness actions the job needs (for example `harness:task:create` and `harness:task:read`, see [Permissions](https://hexelstudio.com/docs/harness/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.

```yaml .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

<Note>
Workload identity federation is off for each organization until an admin turns it on with `PUT /v1/workload-identity-providers/federation` `{"enabled": true}` (`iam:workload_identity_provider:write`). See [Turn federation on](https://hexelstudio.com/docs/identity/workload-identity#turn-federation-on-for-your-organization). Until it is on, use an API key.
</Note>

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](https://hexelstudio.com/docs/identity/workload-identity), [Roles](https://hexelstudio.com/docs/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:

```yaml .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.
