Skip to content

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

  • curl and jq on the CI runner (the steps below call the REST API directly; the TypeScript SDK exposes the same calls as client.agents.register and client.agents.deactivate)
  • An API key with the write:nhi scope, minted in Platform Config → Integrations & API → API Keys and stored as a CI secret (ATMANID_CI_KEY). write:nhi is a high-impact scope, so the dialog shows Submit for Approval and the key is issued once an administrator approves it. Don’t add write:access_requests to 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:

.github/workflows/deploy.yml
- 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 duplicate
  • managed_by = github-action-deploy-pipeline — the GitOps boundary. GET /api/v1/agents?managed_by=github-action-deploy-pipeline lists exactly the agents this workflow owns. See Register an NHI with the TypeScript SDK for the architectural reasoning.
  • name includes repository_id + run_id — unique within the tenant, which matters because registering a name that already exists returns 409. 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}/scope endpoint. 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_REVIEW agents — 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:

Terminal window
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_state carries the name, owner, environment, purpose and idempotency key
  • AGENT_DEACTIVATED — written when the final step ran, with your reason

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_by tag. Without it, agents can’t be filtered as a group. Always set it to your workflow identifier.
  • Wrong environment casing. production is rejected; the API accepts Production, Staging, Development or Testing.
  • No deactivate-on-failure. Without if: always(), failed deploys leave agents alive. Run-away cost + violates least-privilege.
  • Missing idempotency_key on deactivate. The deactivate endpoint requires one, just like registration.
  • Exposing the CI key to forks. Keep ATMANID_CI_KEY out of workflows that run on pull requests from forks, or a fork can register agents in your tenant.

Going further

© AtmanID · Privacy