sentryagent-idp/openspec/changes/archive/2026-04-02-phase-4-developer-growth/specs/github-actions/spec.md at eea885db0447bddc82b3268ca4cf3465453686e6

Files

SentryAgent.ai Developer 831e91c467 chore(openspec): archive phase-4-developer-growth change

All 90 tasks complete. Phase 4 — Developer Growth & Go-to-Market
fully delivered and archived per OpenSpec protocol.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-02 15:17:18 +00:00

3.3 KiB

Raw Blame History

ADDED Requirements

Requirement: register-agent Action registers an agent in CI using OIDC

The system SHALL provide a GitHub Action at .github/actions/register-agent/action.yml (sentryagent/register-agent@v1) that registers a new agent via the SentryAgent.ai API using GitHub OIDC token exchange. The Action SHALL accept inputs: api-url (required), agent-name (required), agent-description (optional). The Action SHALL output: agent-id. No long-lived API credentials SHALL be required.

Scenario: Agent registered in CI workflow

WHEN a GitHub Actions workflow includes uses: sentryagent/register-agent@v1 with valid api-url and agent-name inputs
THEN the step completes successfully, an agent is registered in SentryAgent.ai, and steps.<id>.outputs.agent-id is populated

Scenario: OIDC exchange fails — action fails with clear message

WHEN the GitHub OIDC token cannot be exchanged (e.g., trust policy not configured)
THEN the action fails with an error message explaining how to configure the OIDC trust policy

Requirement: issue-token Action issues an OAuth2 token in CI using OIDC

The system SHALL provide a GitHub Action at .github/actions/issue-token/action.yml (sentryagent/issue-token@v1) that issues an OAuth2 access token for an agent via OIDC exchange. The Action SHALL accept inputs: api-url (required), agent-id (required). The Action SHALL output: access-token, expires-at. The access token SHALL be masked in GitHub Actions logs.

Scenario: Token issued in CI workflow

WHEN a GitHub Actions workflow includes uses: sentryagent/issue-token@v1 with api-url and agent-id
THEN the step completes and steps.<id>.outputs.access-token contains a valid Bearer token

Scenario: Access token is masked in logs

WHEN the action issues a token
THEN the token value is registered with core.setSecret() and does not appear in plaintext in the workflow log

Requirement: GitHub OIDC trust policy is configurable via API

The system SHALL allow tenants to register a GitHub OIDC trust policy via POST /oidc/trust-policies specifying: provider: "github", repository (e.g., org/repo), branch (optional), and agentId. Only workflows matching the trust policy SHALL be permitted to exchange GitHub OIDC tokens for SentryAgent.ai agent tokens.

Scenario: Trust policy restricts token exchange to specified repo

WHEN a trust policy is registered for org/repo-a and a GitHub OIDC token from org/repo-b is presented
THEN the token exchange is rejected with HTTP 403

Scenario: Trust policy permits token exchange for matching repo

WHEN a trust policy is registered for org/repo-a and a valid GitHub OIDC token from org/repo-a is presented
THEN the token exchange succeeds and an agent access token is returned

Requirement: Both Actions include README with setup instructions

Each Action directory SHALL include a README.md with: purpose, prerequisites (OIDC trust policy setup), inputs table, outputs table, a minimal workflow example, and a link to full documentation on the developer portal.

Scenario: README is present and complete

WHEN a developer reads register-agent/README.md
THEN they can configure the OIDC trust policy and add the action to their workflow without external documentation

3.3 KiB Raw Blame History