GitOps NHI lifecycle with the jml-sync GitHub Action
What you’ll do
You’re Dev Torres. Your team owns 8 NHIs (service accounts + AI agents) for the payments domain. Today they’re managed through ad-hoc curl calls when someone remembers — there’s no canonical source-of-truth for “what NHIs SHOULD exist.” If a teammate accidentally deletes one, nobody notices for weeks. After this tutorial, the manifest IS the source-of-truth, every diff is auditable, and a daily drift check catches any out-of-band changes.
This walks the canonical GitOps-NHI scenario, the highest-leverage automation pattern for teams managing >5 NHIs. Time investment: ~30 min for first manifest + perpetual zero-touch on every commit.
Prerequisites
- Repo where you’ll commit the manifest (any Git provider with GitHub Actions or compatible CI)
- An AtmanID API key with three scopes:
read:nhi+write:nhi+read:audit_logs. Mint at Platform Config → Integrations & API → API keys. Store as repo secretATMANID_API_KEY. - Access to the
atmanid/jml-syncaction. It is an internal action today — not published to the GitHub Marketplace — so ask AtmanID for access before you start (see Going further). - Familiarity with Register an NHI via curl — this tutorial wraps the API in a declarative YAML interface
The shape of GitOps for NHIs
The mental model that makes this work:
nhi-manifest.yaml in repo ──push──> GitHub Action runs jml-sync ↓ Diff vs AtmanID tenant ↓ ┌─────────────┼─────────────┐ ↓ ↓ ↓ CREATED UPDATED DEACTIVATED ↓ Audit row per change with X-Request-Id linking back to the workflow runThree things to internalize:
- The manifest is the desired state. Anything in the manifest but not in tenant → CREATE. Anything in tenant but not in manifest → DEACTIVATE. Anything different between the two → UPDATE.
- The
managed_byfield is the GitOps boundary. The action only sees agents tagged with the manifest’smanaged_byvalue. Without this, the diff engine would consider EVERY agent in your tenant — including seed data and other-team agents — as candidates for DEACTIVATE. - Every change audits. Every CREATE/UPDATE/DEACTIVATE writes an audit record carrying the
request_idof that API call, and the run summary links each row to it. Auditors trace from “this NHI was deactivated on date X” back to “the workflow run that made the call.”
Step 1 — Create the manifest
Commit nhi-manifest.yaml to your repo root:
apiVersion: atmanid.dev/v1kind: NHIManifestmetadata: # CRITICAL: managed_by is the GitOps boundary. The action only operates # on agents tagged with this value. Without it, the diff engine would # see your entire tenant and classify every unrelated agent as DEACTIVATE. managed_by: my-payments-workflow
spec: agents: - name: stripe-webhook-listener type: External AI Tool framework: node-stripe-sdk owner_team: payments owner_email: payments-eng@example.com environment: Production vendor: stripe purpose: Listens for Stripe webhook events and triggers reconciliation
- name: nightly-reconciler type: Service Account owner_team: payments owner_email: payments-eng@example.com environment: Production purpose: Runs daily payment reconciliation against ledgerPick managed_by carefully. It’s the namespace for this workflow’s agents. Convention: <repo-name>-<purpose> (e.g., acme-payments-workflow, acme-platform-deploy-pipeline). Once chosen, do NOT change it — changing breaks the GitOps boundary because previously-tagged agents become “unmanaged” from the diff engine’s view.
Step 2 — Add the workflow
Commit .github/workflows/sync-nhis.yml:
name: Sync NHIs to AtmanID
on: push: paths: [ nhi-manifest.yaml ] workflow_dispatch: inputs: dry_run: description: 'Run as dry-run (no mutations)' type: boolean default: true
jobs: sync: runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v4 - uses: atmanid/jml-sync@v1 with: api_key: ${{ secrets.ATMANID_API_KEY }} manifest_path: nhi-manifest.yaml dry_run: ${{ github.event.inputs.dry_run || 'false' }} # safety guard — refuse to apply a plan that # would deactivate more than this many rows. Default 3. max_deactivates: 3Three workflow design decisions worth understanding:
paths: [nhi-manifest.yaml]— the workflow only runs when the manifest changes. Saves CI minutes for unrelated commits.workflow_dispatchwithdry_runinput — lets you trigger a manual dry-run from the Actions tab to preview changes before they apply. Useful for “what would happen if I added this agent” exploration.max_deactivates: 3— refuses to apply a plan that would deactivate more than 3 rows. This is the belt-and-braces against catastrophic mistakes (e.g., accidentally deleting all spec.agents from the manifest would otherwise trigger mass deactivation).
Step 3 — First run with dry_run=true
NEVER apply for the first time. Always dry-run first:
- Go to GitHub Actions → “Sync NHIs to AtmanID” workflow → Run workflow → check the dry_run box → Run
- Wait ~30 seconds for the action to complete
- Open the workflow run summary
The run log shows the plan, one line per intended change:
atmanid/jml-sync — dry-run mode [1] would CREATE: stripe-webhook-listener (External AI Tool) [2] would CREATE: nightly-reconciler (Service Account)The step summary (“AtmanID JML Sync — dry-run run”) lists the same rows in a table (#, Name, Status, Agent ID, Audit) with status DRY_RUN; nothing is changed.
Verify the plan matches your expectation. If yes, re-run without dry_run; the action applies the plan + writes audit rows. New agents are created in PENDING_REVIEW (see What’s NOT covered).
Step 4 — Verify in the audit trail
After the apply run, open AtmanID → Security & Risk → Audit & Forensics and search for the request_id shown in the workflow run summary, or list the registrations from the audit API and match the same request_id:
curl -s "$ATMANID_BASE_URL/api/v1/audit?action_type=AGENT_REGISTERED&since=2026-10-08T00:00:00Z" \ -H "Authorization: Bearer $ATMANID_API_KEY"Expected: 2 rows — AGENT_REGISTERED for stripe-webhook-listener + AGENT_REGISTERED for nightly-reconciler, each with the agent’s name, type, owner and environment in new_state. The managed_by tag is on the agent itself: GET /api/v1/agents?managed_by=my-payments-workflow returns both.
The forensic chain is intact: workflow run → request_id → audit records → the registered agents. An auditor asking “when was stripe-webhook-listener created” gets a complete answer in one query.
Step 5 — Mover scenario (UPDATE)
Three months later, nightly-reconciler should run in Staging not Production (engineering is decommissioning the dedicated prod-only nightly job in favor of a staging-then-promote pattern). Edit the manifest:
- name: nightly-reconciler type: Service Account owner_team: payments owner_email: payments-eng@example.com environment: Staging # ← changed from ProductionCommit + push. Workflow fires. Run summary:
nightly-reconciler UPDATED (fields: environment)stripe-webhook-listener SKIPPED_NOOPAudit row: AGENT_UPDATED with new_state.updated_fields = ["environment"] and new_state.diff.environment = { "from": "Production", "to": "Staging" }. The change is tracked + reversible (revert the YAML commit, push, workflow re-applies the prior state).
Step 6 — Leaver scenario (DEACTIVATE)
stripe-webhook-listener is being decommissioned (the team migrated to Stripe’s hosted webhook routing). Remove the entry from the manifest:
spec: agents: # stripe-webhook-listener removed (migrated to Stripe hosted routing — 2026-08) - name: nightly-reconciler ...Commit + push. Workflow fires. Run summary:
stripe-webhook-listener DEACTIVATEDnightly-reconciler SKIPPED_NOOPThe agent’s status flips to DEPROVISIONED (soft-delete; we never hard-delete). Audit row: AGENT_DEACTIVATED with new_state.status = "DEPROVISIONED" and new_state.previous_status set to the status it had (e.g. "ACTIVE").
If you accidentally remove the agent (the deactivation was unintended), reverting the commit does not bring it back: the deprovisioned agent still holds its name, so the re-create is refused (AGENT_NAME_CONFLICT) and the run reports the row as SKIPPED_EXISTS. Restore it under a new name, or ask an administrator to resolve the old registration first. The prior agent stays soft-deleted for forensic continuity.
Step 7 — Daily drift check
Schedule a daily dry-run so drift shows up in the run summary:
on: schedule: - cron: '0 6 * * *' # 6am UTC dailyjobs: drift-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - id: sync uses: atmanid/jml-sync@v1 with: api_key: ${{ secrets.ATMANID_API_KEY }} manifest_path: nhi-manifest.yaml dry_run: true # Always dry — drift detection onlyAny row other than SKIPPED_NOOP in the summary is drift. The action has no “changes detected” output today (its outputs are agents_created, rows_succeeded, rows_failed and summary_url), so an automatic Slack or email alert needs your own step — for example one that checks the run log for would CREATE, would UPDATE or would DEACTIVATE lines.
This catches:
- Manual changes someone made via the AtmanID dashboard (out-of-band)
- Changes someone made via direct API call (out-of-band)
- Agents that someone created via dashboard but forgot to add to manifest
The drift alert is your “is GitOps actually being respected” canary. Without it, the manifest can drift from reality silently.
How the safety layers work
Two layers protect you from catastrophic mistakes:
Layer 1 (architectural) — managed_by GitOps boundary
The diff engine ONLY considers agents tagged with managed_by: my-payments-workflow. Agents tagged with another value, or not tagged at all, never appear in the plan — so they can never be classified as DEACTIVATE. (A manifest must list at least one agent; an empty spec.agents is rejected before any diff.)
This is the FIRST defense. A misconfigured workflow can’t accidentally affect agents owned by a different workflow OR untagged seed data.
Layer 2 (belt-and-braces) — max_deactivates safety guard
If your manifest legitimately had 50 agents and you accidentally delete 47 of them in a commit, Layer 1 doesn’t catch it (those 47 ARE in your managed_by namespace). Layer 2 does: the action refuses to apply a plan that would DEACTIVATE more than max_deactivates (default 3) rows.
The override is force_deactivate: true — explicit opt-in for the rare case you intend a bulk leaver event (e.g., team disbandment).
The combination means: a misconfigured workflow can’t affect other teams’ agents (Layer 1) AND can’t catastrophically affect your own team’s agents (Layer 2).
Lesson cited from the design history
An early dogfood run surfaced the need for the managed_by boundary. The original GitOps design didn’t have this boundary; the first dogfood run treated the entire tenant as in-scope and would have soft-deleted 18 unrelated agents had it not been caught and reverted via SQL. The two-layer safety design above is the architectural fix, not a band-aid. Worth understanding because it explains why both layers exist — neither alone is sufficient.
See Set up an external auditor for SOC 2 evidence collection Step 5 (audit chain integrity) for the auditor-side perspective on why the GitOps audit trail matters for compliance.
What just happened
You converted “ad-hoc NHI management” into:
- Manifest-as-source-of-truth — the YAML IS the canonical NHI inventory
- Auditable changes — every CREATE/UPDATE/DEACTIVATE traceable from workflow run → audit row
- Drift detection — daily check catches out-of-band changes
- Two-layer safety — managed_by boundary + max_deactivates guard prevent catastrophic mistakes
This is the shape of GitOps NHI management — same flow whether you have 2 NHIs or 200. The investment scales with team size (a team of 1 won’t bother; a team of 8+ benefits a lot).
Common pitfalls
- Forgetting
managed_byin metadata. The action still runs, but warns and diffs against EVERY agent in the tenant — only themax_deactivatesguard stands between you and mass deactivation. Always set it. And if you set it AND later try to change it, you orphan your existing agents — they keep the old tag, your new manifest sees zero matching agents, and the plan would CREATE-everything-anew + DEACTIVATE-nothing (because Layer 1 hides them). Once chosen, never change. - First run without dry_run. Always dry-run first. The 30-second cost is worth it.
- Removing entries when you mean to update them. A typo in the agent name reads as “remove the old + add a new.” The diff engine sees a DEACTIVATE + CREATE with the new name — and the old name stays reserved by the deactivated agent. If max_deactivates=3, small typos get through; if it’s a bulk rename, you’ll trigger the safety guard.
- No drift check. Without it, the manifest silently diverges from reality. Always set up the daily drift detection.
- Letting
managed_byapply across multiple repos. Each workflow should have its own uniquemanaged_by. Two workflows sharing amanaged_bysee each other’s agents — both think they’re the source-of-truth, which is the recipe for fights.
Going further
- For per-call SDK depth (e.g., if you want to write a custom GitOps tool instead of using the action), see Register an NHI with the TypeScript SDK
- For the API spec including the
managed_byfield details, see API Reference/api/v1/agentsendpoints + the v1.7.0 changelog entry for the managed_by introduction - For the auditor’s perspective on verifying GitOps changes, see Set up an external auditor for SOC 2 evidence collection
- The GitHub Action is internal today (not on the Marketplace); its source publishes to the AtmanID GitHub org at open-sourcing (post-incorporation). Until then, email hello@atmanid.com for access and the full input/output reference. Inputs:
api_key,api_base_url,manifest_path(defaultnhi-manifest.yaml),dry_run,fail_on_error(defaulttrue),max_deactivates(default 3),force_deactivate.
What’s NOT covered by jml-sync today
Honest accounting:
- Human (Joiner/Mover/Leaver) lifecycle. This action handles NHI lifecycle only. For human JML, see Onboard a Joiner / Mover / Leaver lifecycle.
- Approval of NHI registration. Every agent the action creates lands in
PENDING_REVIEW, and an administrator must approve it before full policy enforcement applies. The action does not approve agents or configure any auto-approval. - JIT capability elevation. The action manages the agent’s existence but not its scope. There is no JIT endpoint in the public
/api/v1surface today; see the CI/CD SDK tutorial for how elevation is handled. - Cross-tenant federation. Each manifest applies to one tenant. Multi-tenant scenarios need one manifest per tenant.
© AtmanID · Privacy