Skip to main content

Argo CD Integration

Overview​

Argo CD deploys your baseline environment from Git. Signadot sandboxes add forked versions of a few workloads next to that baseline, and only requests that carry a sandbox's routing key reach them. The two don't conflict: Argo CD keeps reconciling the baseline, and the forks stay outside every Argo CD Application.

There are three ways to connect them:

ApproachCreates the sandboxRuns the testsUse it when
Argo CD only manages the baselineCI, for example the Signadot Sandbox ActionCIYou already build and test pull requests in CI and want Argo CD untouched.
ApplicationSet with hooksAn Argo CD hook JobAn Argo CD PostSync hookYou want Argo CD to own the preview's lifecycle and report results, for example to coding agents through the Argo CD MCP server.
ApplicationSet, tests in CIAn Argo CD hook JobCI, using the sandbox's routing keyArgo CD owns the lifecycle, but your test suites and reports already live in CI.

Test Coding Agent Pull Requests with Argo CD walks through the second approach end to end.

How sandboxes coexist with Argo CD​

Checked with Argo CD v3.5.6 and Signadot Operator 1.4.0:

  • Forks aren't tracked. A forked Deployment or Service doesn't carry the baseline's argocd.argoproj.io/tracking-id annotation (or app.kubernetes.io/instance label), so Argo CD doesn't consider it part of any Application. Forks don't make the baseline OutOfSync, and pruning never deletes them.
  • Forks aren't orphans. A fork's Deployment and Service are owned by a ForkedWorkload in the same namespace, which is owned by a cluster-scoped SignadotSandbox. Argo CD reports only top-level resources as orphaned, so with orphanedResources.warn on, sandboxes add no warnings and need no ignore rule.
  • DevMesh doesn't cause drift. The Signadot Operator injects the DevMesh sidecar when Pods are created, so the Deployments you keep in Git stay as they are.
  • Argo Rollouts can be forked. Set forkOf.kind: Rollout in the sandbox specification. Rollouts that use workloadRef aren't supported.

ApplicationSet with hooks​

An ApplicationSet with the pull request generator creates one Application per open pull request and deletes it when the pull request closes. Each Application renders a small chart that holds the sandbox specification and three hook Jobs:

HookJob
SyncWait for CI to push the pull request's image, then run signadot sandbox apply.
PostSyncLook up the sandbox's routing key and run the end-to-end tests with it.
PostDeleteRun signadot sandbox delete.

The Jobs use the Signadot CLI image (signadot/signadot-cli, with the binary at /signadot) and read SIGNADOT_ORG and SIGNADOT_API_KEY from a secret in the preview namespace. Give only the containers you write that secret: the container that runs the pull request's own tests should get the routing key, not the API key.

Keep the chart in a repository your platform team controls, not in the app repository the pull requests come from, and pin its targetRevision. Otherwise a pull request can change how its own preview is created and tested.

Settings that matter​

SettingWhy
A non-hook resource that changes with every commitArgo CD doesn't count hooks when it compares an Application with Git, so an Application that holds only hooks stays Synced and never reruns them. Put the sandbox specification in a ConfigMap that includes the commit.
Constant sandbox name and descriptionBoth are immutable. A description that includes the commit makes every update after the first fail with cannot update description. See sandbox updates.
syncPolicy.retry.limitArgo CD 3.5 retries a failed automated sync five times by default, which delays a failing result by minutes. Set limit: 0 to report a failure at once; the next commit retries.
argocd.argoproj.io/hook-delete-policy: BeforeHookCreationKeeps each hook Job, and its logs, until the next sync replaces it.
Pod in the AppProject's namespaceResourceWhitelistArgo CD hides child resources whose kinds the project doesn't allow. Without Pod, the hook Jobs' Pods vanish from the resource tree, and Argo CD can't return their logs.
A sandbox ttlA backstop if the PostDelete hook never runs, for example because of argoproj/argo-cd#29100. See TTL.
requeueAfterSeconds or a webhookThe pull request generator polls every 30 minutes by default. Lower requeueAfterSeconds for a local cluster, or configure a GitHub webhook in production.

Commit statuses with Argo CD Notifications​

Argo CD Notifications' github service supports only GitHub App credentials. To set a commit status with a token, use the webhook service against the GitHub API, and send one result per sync operation:

argocd-notifications-cm (excerpt)
  service.webhook.github: |
    url: https://api.github.com
    headers:
      - name: Authorization
        value: token $github-token
  trigger.on-preview-completed: |
    - when: app.status.operationState?.phase in ['Succeeded', 'Failed', 'Error']
      oncePer: app.status.operationState?.startedAt
      send: [preview-result]

Key oncePer on the operation, not on the commit. With the commit as the key, a second sync of the same commit, for example after the chart changes, never reports its result, and the status stays pending.

If you apply settings like these to argocd-cm or argocd-notifications-cm with kubectl apply --server-side, use your own --field-manager. Under the default kubectl manager, the apply removes the defaults the Argo CD install put there.

Coding agents and the Argo CD MCP server​

The Argo CD MCP server (argocd-mcp on npm) lets an agent read Application status, events, resource trees and workload logs. With MCP_READ_ONLY=true, it removes the tools that create, update, delete or sync Applications or run resource actions. Give it a local account that can read only preview Applications:

argocd-cm and argocd-rbac-cm (excerpt)
  accounts.agent: apiKey
---
  policy.csv: |
    p, agent, applications, get, previews/*, allow
    p, agent, logs, get, previews/*, allow

Argo CD 3.0 and later enforce the logs permission, so grant it explicitly. The server's get_application_workload_logs tool resolves a Job's Pods through the resource tree and returns the last 100 lines, so end your test output with a short summary.

Akuity Platform​

Akuity Platform runs upstream Argo CD, so ApplicationSets, hooks and Notifications work as described above. According to Akuity's documentation:

  • TokenRef strict mode is on by default. A pull request generator's tokenRef can only read secrets labeled argocd.argoproj.io/secret-type: scm-creds, such as the platform-managed application-set-secret. See the instance settings.
  • Agents can use the Akuity MCP Server. It is part of the Agentic Control Plane, its guardrail level is read-only by default, and its tool names differ from the open source server's, for example get_argocd_application. See the MCP server docs.

The tutorial was tested on open source Argo CD.

Frequently asked questions​

Does Signadot work with Argo CD?​

Yes. Argo CD keeps deploying your baseline from Git, and Signadot sandboxes add forked workloads next to it that receive only requests carrying their routing key. Argo CD can also manage the sandboxes themselves: an ApplicationSet with the pull request generator can create, test and delete a sandbox for every pull request through hook Jobs.

Will Argo CD prune Signadot sandbox forks or mark my Application OutOfSync?​

No. Forked workloads don't carry the baseline's Argo CD tracking annotation or label, so Argo CD never treats them as part of an Application. They don't cause OutOfSync, and pruning never deletes them.

Do sandbox forks show up as orphaned resources in Argo CD?​

No. A fork's Deployment and Service are owned by a ForkedWorkload, which is owned by a cluster-scoped SignadotSandbox. Argo CD only reports top-level resources as orphaned, so no ignore rule is needed.

Should Argo CD or CI run the tests against a sandbox?​

Either works. Running them as an Argo CD PostSync hook keeps the tests in the cluster next to the sandbox, needs no network path from CI to the cluster, and puts the result where Argo CD users and agents already look. Running them in CI suits suites that already live there and need CI's reporting, but CI then needs the routing key, and so a Signadot API key.

Does Signadot support Argo Rollouts?​

Yes. A sandbox can fork an Argo Rollout as well as a Deployment by setting forkOf.kind to Rollout. Rollouts that use workloadRef aren't supported.

Does this work on Akuity Platform?​

Akuity Platform runs upstream Argo CD, so ApplicationSets, hooks and Notifications work the same way. Its TokenRef strict mode is on by default, so a pull request generator's tokenRef must point at the platform-managed application-set-secret or another secret labeled argocd.argoproj.io/secret-type: scm-creds. For agents, the Akuity MCP Server is read-only by default.

See also​