Suppose a deployment creates an agent, then fails before updating its schedule. The CI job is red, but the new agent still exists. If the next job starts from an older resource map, it may create a duplicate and leave the operator with more to clean up.
That is the release case to design for with ant apply. Anthropic introduced the command in CLI 1.30.0 on September 3, 2026. It manages Claude API agents, environments, skills, memory stores, and deployments from repository files. This guide turns the documented behavior into a CI review and recovery procedure. The opening scenario and script below are illustrative; General Analysis has not run a Managed Agents deployment for this article.
Establish the resource identity before automating#
Install the Claude API CLI using Anthropic's quickstart, verify that it is version 1.30.0 or later, and choose one repository root for the project. The API CLI is a separate tool from Claude Code. A Claude Code rollout has a different control problem, covered in securing coding agents.
The CLI repository explains that claude-lock.json maps local files to remote resource IDs and records their organization and workspace. Keep it under review with the resource definitions. Treat a change to that mapping as a deployment change, even when the agent's prompt is unchanged.
For an existing Console project, use Export as code and retain its included lockfile. Applying a new definition alone cannot adopt an existing resource. For a new project, review the initial plan and commit the generated mapping before another writer takes over. These behaviors are documented in the apply guide.
Assign one owner to each deployment target's lockfile. Record the target workspace, the approved source commit, and the resulting lockfile commit together. Copying a production lockfile into a staging directory does not change the destination recorded inside it.
See how your AI systems hold up under real attacks
General Analysis maps AI applications and agents, red teams prompts, retrieval, tools, MCP servers, browser actions, permissions, and business workflows, then turns findings into evidence your team can reproduce and retest.
Bind CI credentials to the intended workload#
Anthropic's Workload Identity Federation exchanges an identity-provider token for an Anthropic token associated with a service account. An administrator configures the issuer, federation rule, and service account in Claude Console. Match the workload claims narrowly and review the granted scope; the documented default, workspace:developer, carries workspace API-key-level access.
For GitHub Actions, the provider guide distinguishes branch, pull-request, and environment subjects. An environment-bound subject has this form: repo:<owner>/<repo>:environment:<name>. Configure the trust rule for the approved repository and deployment context, then require review on that GitHub environment. A pull request should not inherit the production deployment identity merely because it needs to show a plan.
Check credential selection too. The CLI's authentication reference documents several credential sources. Use ant auth status in the controlled runner to confirm the intended source; remove unintended API-key overrides from that job. Keep identity tokens out of logs and recovery artifacts.
Workspace matching is useful protection against an accidental destination change. It does not establish that the proposed prompt, tool access, or schedule deserves approval. Review those definitions before granting the job authority to apply them.
Decide what each change is allowed to do#
Use ant apply --dry-run . to produce the review plan. The command exits zero even when that plan is blocked, so a green PR check cannot stand in for reading it. After approval, ant apply --yes . discovers new resource files; bare --yes reconciles tracked files only. See the current apply behavior.
| Situation | Documented behavior | Recommended release decision |
|---|---|---|
| A referenced skill changes | References track specific versions | Review the dependent agent changes in the same plan |
| A GitHub-hosted skill branch moves | Its resolved commit stays pinned until --upgrade | Make dependency upgrades explicit review events |
| Someone edits a resource in Console | Apply refuses the drift unless forced | Reconcile the emergency edit before another release |
| A tracked definition disappears | The remote resource remains unless pruned | Decide whether to retire it; do not infer retirement from a Git deletion |
| An apply fails partway | Its lockfile records completed creations | Recover that state before retrying |
Sources: reference and drift semantics, partial-apply persistence. The release decisions are General Analysis recommendations.
Keep --force, --prune, and --upgrade out of the routine command. Each expands the meaning of a release: overwriting an external edit, retiring resources, or changing a dependency. A reviewer should be able to approve those effects separately.
Preserve failure state without hiding the failure#
Use one writer for the target, including its state-persistence step. A GitHub Actions concurrency group can serialize jobs within a repository. Set cancel-in-progress: false for a state-changing deployment so a newer commit does not cancel it halfway through. This does not coordinate a developer's laptop or another repository; reserve target writes for the controlled release process.
The apply guide requires preserving the updated lockfile even after a partial failure. The Bash fragment below illustrates a recovery copy while retaining the original exit status. It assumes the CLI is installed, federation is configured, the reviewed checkout is at the project root, and the caller supplies a private recovery directory outside the checkout. It performs a real apply if executed; it is not a complete CI workflow.
Code source: illustrative
set -euo pipefail
: "${RECOVERY_DIR:?Set a private recovery directory outside the checkout}"
umask 077
mkdir -p "$RECOVERY_DIR"
apply_status=0
ant apply --yes . || apply_status=$?
if [[ -f claude-lock.json ]]; then
cp claude-lock.json "$RECOVERY_DIR/claude-lock.json"
fi
git rev-parse HEAD > "$RECOVERY_DIR/source-commit.txt"
printf '%s\n' "$apply_status" > "$RECOVERY_DIR/apply-status.txt"
exit "$apply_status"
Configure a subsequent CI step to retain that directory even when the apply step fails. Limit artifact access and retention. The copy helps recovery, but another deployment must wait until the repository contains the reconciled lockfile.
If the job fails, pause the release queue. Recover its source commit, plan, exit status, and lockfile, then compare the recorded resource IDs with the remote state. Persist the reconciled mapping through the repository's approved write path. Generate a fresh plan from that state before retrying. If state persistence fails, keep the release blocked even if the API changes succeeded.
Do not delete the lockfile to get a clean retry. Do not automatically retry with --force either: that can overwrite an external edit before an operator has accounted for it. A rollback needs a fresh plan against current remote state; a Git revert alone does not verify the running configuration.
Verify the deployed configuration and the running sessions#
After apply succeeds, inspect the resulting resource IDs and versions. Check the deployment's selected agent, environment, schedule, and resource access against the approved plan. Keep this evidence with the source and state commits. A successful CLI exit is one part of that record.
Scheduled work has its own lifecycle. Anthropic's deployment documentation says pausing suppresses future scheduled triggers, while existing sessions continue and manual runs remain possible. For an incident involving an already-running agent, pausing its schedule alone is therefore insufficient. Identify active sessions and apply the appropriate session and downstream access controls.
For the wider evidence strategy, the Claude Compliance API guide explains how retained activity differs from runtime enforcement. Do not assume a deployment record proves that every subsequent tool action was authorized.
Before enabling unattended releases, have the deployment owner locate the last persisted lockfile and walk through recovery after a partial apply. They should be able to recover the source commit and resource mapping after the runner has gone away.
