sentryagent-idp/openspec/changes/phase-4-developer-growth/specs/github-actions/spec.md at b0f70b7ac4d1bc4c4d7a8a3402eff7e510eb7135

Files

SentryAgent.ai Developer b0f70b7ac4 feat(openspec): Phase 4 Developer Growth & Go-to-Market Readiness

OpenSpec change: phase-4-developer-growth (spec-driven, 4/4 artifacts)

6 workstreams, 90 implementation tasks, delivery sequence:
WS1 → WS2 + WS3 (parallel) → WS4 → WS5 → WS6

Workstreams:
1. Production Hardening — ioredis rate limiting, DB pool tuning, /health/detailed, k6 load tests
2. Developer Portal — Next.js 14, Swagger UI explorer, onboarding wizard, pricing/SDK pages
3. CLI Tool — sentryagent npm CLI, 5 commands, shell completion
4. Agent Marketplace — public searchable registry powered by existing agent/DID infrastructure
5. GitHub Actions — register-agent + issue-token Actions via OIDC (no stored secrets)
6. Billing & Usage Metering — Stripe Checkout, webhook-driven state, free tier enforcement

New capabilities (8 specs): production-hardening, developer-portal, cli-tool,
agent-marketplace, github-actions, billing-metering (+delta: web-dashboard, monitoring)

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

2026-04-02 04:00:34 +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