Integrate AtmanID into a CI/CD pipeline via the SDK
What you’ll do
You’re Dev Torres, platform engineer at Acme Corp. The CI/CD pipeline currently uses one shared “deploy bot” account for every deploy across every environment. Your security team flagged this — there’s no per-deploy attribution and nothing ever expires. After this tutorial, every CI/CD run registers its own agent identity, deactivates it cleanly when the run ends (success, failure or rollback), and leaves an audit trail tied to the run.
Time investment: ~30 min for the first integration + ~2 min/deploy in pipeline overhead.
Prerequisites
curlandjqon the CI runner (the steps below call the REST API directly; the TypeScript SDK exposes the same calls asclient.agents.registerandclient.agents.deactivate)- An API key with the
write:nhiscope, minted in Platform Config → Integrations & API → API Keys and stored as a CI secret (ATMANID_CI_KEY).write:nhiis a high-impact scope, so the dialog shows Submit for Approval and the key is issued once an administrator approves it. Don’t addwrite:access_requeststo the same key — that combination is blocked. The key’s owner must also hold permission to manage NHIs - Your tenant’s base URL available to the job as
ATMANID_BASE_URL(a repository variable or secret) - Your CI/CD platform — examples below use GitHub Actions, but the pattern is identical for GitLab CI, Jenkins, CircleCI
Step 1 — Register the agent at deploy start
Add this step at the top of your deploy job:
- name: Register deploy agent with AtmanID id: register-agent run: | AGENT_RESPONSE=$(curl -sS --fail-with-body -X POST \ -H "Authorization: Bearer $ATMANID_CI_KEY" \ -H "Content-Type: application/json" \ -d "{ \"idempotency_key\": \"deploy-${{ github.run_id }}\", \"name\": \"deploy-${{ github.repository_id }}-${{ github.run_id }}\", \"type\": \"CI/CD Pipeline\", \"framework\": \"github-actions\", \"owner_team\": \"platform\", \"owner_email\": \"platform-eng@example.com\", \"environment\": \"${{ inputs.environment }}\", \"managed_by\": \"github-action-deploy-pipeline\", \"purpose\": \"Deploy run for ${{ github.repository }} commit ${{ github.sha }}\" }" \ "$ATMANID_BASE_URL/api/v1/agents") AGENT_ID=$(echo "$AGENT_RESPONSE" | jq -r '.agent_id') echo "agent_id=$AGENT_ID" >> $GITHUB_OUTPUT env: ATMANID_CI_KEY: ${{ secrets.ATMANID_CI_KEY }} ATMANID_BASE_URL: ${{ vars.ATMANID_BASE_URL }}environment must be one of Production, Staging, Development or Testing (capitalised exactly so) — map your workflow’s input to one of those values; anything else is rejected with VALIDATION_ERROR.
Three things worth noting:
idempotency_key = deploy-${{ github.run_id }}— a retry within 24 hours with the same key returns the original agent instead of creating a duplicatemanaged_by = github-action-deploy-pipeline— the GitOps boundary.GET /api/v1/agents?managed_by=github-action-deploy-pipelinelists exactly the agents this workflow owns. See Register an NHI with the TypeScript SDK for the architectural reasoning.nameincludesrepository_id+run_id— unique within the tenant, which matters because registering a name that already exists returns409.repository_id(numeric, immutable) instead of repo name (mutable) means rename-safe.
The agent lands in PENDING_REVIEW status. Its record — owner, purpose, environment and the run that created it — is what gives each deploy its own attribution.
Not yet available through the API: scoping, JIT elevation, auto-approval
Earlier versions of this tutorial included three more pipeline steps. None of them has a v1 API endpoint today, so don’t add them to your workflow:
- Per-agent capability scoping — there is no
/api/v1/agents/{id}/scopeendpoint. What the pipeline can do is governed by the scopes on the CI API key itself, so mint a dedicated key with only the scopes the pipeline needs. - JIT elevation for production pushes — there is no
/api/v1/jit/*surface. Agent JIT access is managed in the dashboard under AI Governance → Credentials & Delegation → JIT access, not from CI. - Auto-approval rules for
PENDING_REVIEWagents — there is no auto-approval rule feature. Each registered agent waits for an administrator to review it in AI Governance → AI Tools & Agents → Registry.
The API Reference lists what the v1 agents surface does support: register, list, update and deactivate.
Step 2 — Deactivate when the run ends
Whether the deploy succeeds, fails or is rolled back, deactivate the agent as the job’s last step:
- name: Deactivate deploy agent if: always() # Run even on failure run: | curl -sS --fail-with-body -X POST \ -H "Authorization: Bearer $ATMANID_CI_KEY" \ -H "Content-Type: application/json" \ -d "{ \"idempotency_key\": \"deactivate-${{ github.run_id }}\", \"reason\": \"Deploy ${{ github.sha }} ${{ job.status }}; agent ephemeral\" }" \ "$ATMANID_BASE_URL/api/v1/agents/${{ steps.register-agent.outputs.agent_id }}/deactivate" env: ATMANID_CI_KEY: ${{ secrets.ATMANID_CI_KEY }} ATMANID_BASE_URL: ${{ vars.ATMANID_BASE_URL }}Deactivation is a soft delete: the agent moves to DEPROVISIONED and its record stays for audit.
The if: always() ensures the deactivation runs even if the deploy job failed earlier. Per least-privilege: an agent that was alive only for the duration of the deploy should not persist past it.
Step 3 — Verify in the audit trail
After the deploy completes, verify in AtmanID — each registration is attributed to your CI key. This call needs a key with the read:audit_logs scope:
curl -s "$ATMANID_BASE_URL/api/v1/audit?action_type=AGENT_REGISTERED&since=2026-10-08T00:00:00Z" \ -H "Authorization: Bearer $ATMANID_API_KEY"Match the agent_id from the registration response against each record’s target_resource_id. Run the same query with action_type=AGENT_DEACTIVATED to see the other end of the lifecycle.
Expected output for one run:
AGENT_REGISTERED— your CI key is the actor;new_statecarries the name, owner, environment, purpose and idempotency keyAGENT_DEACTIVATED— written when the final step ran, with yourreason
Both records share the agent’s id as target_resource_id and carry the request_id of the call that wrote them, so an auditor can reconstruct each deploy’s identity from start to finish.
What just happened
You converted “shared deploy bot” into:
- Per-deploy attribution — every deploy registers its own agent, with an owner, purpose and environment on record
- Least-privilege CI credential — a dedicated, approved key carrying only
write:nhi - Ephemeral identity — the agent is deactivated with the deploy, so identities don’t accumulate
Same workflow shape applies to GitLab CI, Jenkins, CircleCI — the API calls are platform-agnostic.
Common pitfalls
- Forgetting
managed_bytag. Without it, agents can’t be filtered as a group. Always set it to your workflow identifier. - Wrong
environmentcasing.productionis rejected; the API acceptsProduction,Staging,DevelopmentorTesting. - No deactivate-on-failure. Without
if: always(), failed deploys leave agents alive. Run-away cost + violates least-privilege. - Missing
idempotency_keyon deactivate. The deactivate endpoint requires one, just like registration. - Exposing the CI key to forks. Keep
ATMANID_CI_KEYout of workflows that run on pull requests from forks, or a fork can register agents in your tenant.
Going further
- For the per-call SDK API depth, see Register an NHI with the TypeScript SDK
- For the GitOps multi-deploy management approach, see Onboard a Joiner / Mover / Leaver lifecycle — JML applies to NHIs too
- For the full agents API (register, list, update, deactivate), see the API Reference
© AtmanID · Privacy