# sentryagent/issue-token

Issues a SentryAgent.ai OAuth2 Bearer token for an existing agent from a GitHub
Actions workflow.

No long-lived API credentials are required. The action uses a GitHub-issued OIDC
token to authenticate with the SentryAgent.ai AgentIdP via `POST /oidc/token`.
The returned access token is automatically masked with `core.setSecret()` so it
never appears in plaintext in workflow logs.

## Prerequisites

### 1. Register the agent

The agent must already exist in SentryAgent.ai. If you need to create the agent
in CI, use [`sentryagent/register-agent@v1`](../register-agent/README.md) first.

### 2. Configure an OIDC Trust Policy for the agent

A trust policy linking the repository to the specific agent must be registered:

```bash
curl -X POST https://idp.sentryagent.ai/api/v1/oidc/trust-policies \
  -H "Authorization: Bearer <your-admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "repository": "org/your-repo",
    "branch": "main",
    "agentId": "<agent-uuid>"
  }'
```

Omit `branch` to allow any branch to issue tokens for this agent.

### 3. Grant `id-token: write` permission

The workflow must have permission to request a GitHub OIDC token:

```yaml
permissions:
  id-token: write
  contents: read
```

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| `api-url` | Yes | Base URL of the SentryAgent.ai API (e.g. `https://idp.sentryagent.ai`) |
| `agent-id` | Yes | UUID of the agent for which to issue an access token |

## Outputs

| Output | Description |
|--------|-------------|
| `access-token` | Short-lived Bearer token. Masked in all log output. |
| `expires-at` | ISO 8601 timestamp indicating when the token expires. |

## Example workflow

```yaml
name: Deploy with Agent Token

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Issue SentryAgent access token
        id: token
        uses: sentryagent/issue-token@v1
        with:
          api-url: https://idp.sentryagent.ai
          agent-id: ${{ vars.SENTRY_AGENT_ID }}

      - name: Call authenticated API
        run: |
          curl -H "Authorization: Bearer ${{ steps.token.outputs.access-token }}" \
            https://my-service.example.com/deploy
```

## Troubleshooting

**HTTP 403 — Trust policy violation**
No trust policy exists for this repository + agent combination. Register a trust
policy using the Prerequisites steps above.

**HTTP 403 — Branch not permitted**
A trust policy exists but specifies a branch constraint that does not match the
current workflow's branch. Add a policy for the current branch, or remove the
branch constraint to allow all branches.

**Failed to obtain a GitHub OIDC token**
Ensure `id-token: write` is set in the workflow's `permissions` block.

**Token expires too quickly**
The default token TTL is set by the SentryAgent.ai server configuration. Check
`expires-at` and re-issue a token before it expires if your workflow is long-running.

## Full documentation

[https://docs.sentryagent.ai/github-actions](https://docs.sentryagent.ai/github-actions)