# sentryagent/register-agent

Registers a new AI agent in SentryAgent.ai 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`, then
calls `POST /agents` to create the agent.

## Prerequisites

### 1. Configure an OIDC Trust Policy

Before this action can exchange tokens, a trust policy must be registered in
SentryAgent.ai for the repository that will run the workflow.

```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"
  }'
```

Omit `branch` to allow any branch to register agents from this repository.

### 2. 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-name` | Yes | Unique name (email format) for the new agent |
| `agent-description` | No | Human-readable description of the agent's purpose |

## Outputs

| Output | Description |
|--------|-------------|
| `agent-id` | UUID of the newly registered agent. Use in subsequent steps to issue tokens or manage credentials. |

## Example workflow

```yaml
name: Register Agent

on:
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

jobs:
  register:
    runs-on: ubuntu-latest
    steps:
      - name: Register SentryAgent
        id: register
        uses: sentryagent/register-agent@v1
        with:
          api-url: https://idp.sentryagent.ai
          agent-name: my-ci-agent@acme.com
          agent-description: CI agent for the acme/my-repo build pipeline

      - name: Print agent ID
        run: echo "Registered agent ${{ steps.register.outputs.agent-id }}"
```

## Troubleshooting

**HTTP 403 — Trust policy not configured**
Register a trust policy for this repository first. See the Prerequisites section above.

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

**Agent registration failed with HTTP 401**
The OIDC token exchange succeeded but the returned access token was rejected by
`POST /agents`. Check that the SentryAgent.ai API version matches and the
bootstrap token has `agents:write` scope.

## Full documentation

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