fefbf1e3ea
- POST /oidc/token: GitHub OIDC JWT exchange (bootstrap + agent-scoped modes) - POST/GET/DELETE /oidc/trust-policies: trust policy CRUD with enforcement - DB migration 022: oidc_trust_policies table with provider/repo/branch/agent_id - GitHub Actions: register-agent and issue-token actions with full READMEs - Trust policy enforcement rejects token exchanges not matching registered policies - Bootstrap mode issues agents:write token for new agent registration without agentId Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
97 lines
2.7 KiB
Markdown
97 lines
2.7 KiB
Markdown
# 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)
|