LangGraph CLI Deployment: Promote the Tested Image to the Right Listener

LangGraph CLI deployment now has a cleaner handoff between building an agent image and promoting it. LangChain’s October 7, 2026 release of langgraph-cli 0.4.33 includes --image-uri for an already-pushed registry image and langgraph deploy listeners list for inspecting workspace listeners. Together, they support an operating rule: deploy the artifact you tested, and decide where it belongs before creating the deployment.

That rule matters when build and deployment run in separate jobs. A passing build job may have a local image; its deployment successor may have only a registry reference. Rebuilding there introduces another artifact into the release chain. Looking up a mutable tag introduces another opportunity for the selected image to change. Carrying the tested digest preserves a precise handoff, while an explicit placement decision prevents an otherwise valid image from reaching an unintended execution location.

This guide covers the Python langgraph deployment interface documented in the selected official reference. Deployment remains beta. The reference also says langgraph deploy is not yet supported on LangSmith Cloud SaaS in AWS. The registry-image path applies to self-hosted LangSmith and workspaces deploying through a listener in their own cluster; it is not a universal replacement for every Cloud deployment method.

Source: LangChain’s langchain-ai/langgraph GitHub release page. The release notes list the already-pushed-image option and listener-list command.

Establish the supported deployment lane

Start by classifying the destination, rather than copying a deployment example from another workspace. The official CLI reference distinguishes managed-registry Cloud deployments from self-hosted and listener-backed deployments using a registry you manage. Its detailed image section documents --image-uri for the latter destinations. A deployment job should know which lane it serves before receiving an artifact.

Use this decision table in the release review:

Destination	Image-promotion decision	Placement decision
Self-hosted LangSmith, bundled operator intended	Use the documented customer-registry path	Leaving placement blank deliberately targets the bundled operator
Self-hosted LangSmith, listener intended	Use a digest-pinned customer-registry image	Inspect listeners and choose the intended listener and namespace
Cloud workspace using a listener in your cluster	Use the documented customer-registry path	A sole listener and sole namespace can be selected automatically
Other managed Cloud deployment	Follow its supported deployment method	Do not infer customer-registry support from this guide
LangSmith Cloud SaaS in AWS	Hold this CLI deployment procedure	The selected reference marks the command unsupported there

The Cloud deployment guide lists a Plus-or-above account and an application that runs locally with langgraph dev as Cloud prerequisites. It also distinguishes UI deployment from a connected GitHub repository and CLI deployment from a local project. Those prerequisites describe Cloud onboarding; they do not establish every self-hosted entitlement or registry permission. Confirm the requirements for your actual destination separately.

Record three answers before promotion: which control plane the assigned runtime already targets, which workspace owns the deployment, and whether the deployment uses the customer-registry source. Do not let a release script choose a different endpoint because a command failed. A failure in the approved lane needs diagnosis, not an automatic move to another destination.

Framework selection and graph orchestration remain separate decisions. Use the existing LangGraph evaluation guide for those questions. Here, the unit of work is a tested container and its intended deployment, rather than the framework’s overall suitability.

Carry the tested digest across the job boundary

The merged image implementation explains the original failure: --push-to always builds, or retags a local image, and pushes. The older --image path inspects the local Docker daemon. A deployment job with no local image cannot use that path as though a registry reference were a local artifact.

--image-uri changes image acquisition. It deploys the registry reference without local inspection, building, tagging or pushing. It requires a digest and rejects a mutable tag or blank input. The final validation change is significant: an earlier commit description mentions a tag or digest, but the reviewed, merged behavior requires the digest. Read the final implementation summary and correction together.

Make the build-to-promotion handoff an explicit sequence:

1. Build the application image in the build lane under its existing approved configuration.
2. Push it to the approved registry and capture the registry digest associated with that push.
3. Run the required checks against the artifact that this digest identifies. If checks preceded the push, preserve evidence connecting the checked artifact to the pushed digest.
4. Store the full repository-and-digest reference with the test results and source revision.
5. Have the deployment lane consume that reference without rebuilding or resolving a newer tag.

The full reference matters. A bare digest does not tell an operator which repository the deployment should pull from. A friendly release tag can remain a human label, but it should not replace the repository-and-digest value in the promotion record. If the handoff contains only a tag, stop and recover the digest from the approved registry evidence before deployment.

A digest identifies an artifact; it does not establish that the artifact is safe, that a graph behaves correctly, or that runtime configuration matches the test environment. Keep those assertions separate. The deployment job should reject a missing test receipt even when the image reference is technically valid. It should also reject a test receipt naming a different digest.

This is an editorial operating practice, not an additional CLI validation feature. The CLI requires the pinned reference; your pipeline supplies the evidence linking that reference to approval. Existing agentic CI/CD guidance covers broader pipeline governance. The narrower promotion gate here asks whether the bytes selected for deployment are the bytes that earned the release.

Choose the image option by artifact location

The three image-related paths solve different acquisition problems. Select one deliberately and avoid assembling a command from incompatible examples.

Option	Artifact available to the job	What the deployment path does
--push-to	Build inputs, or a local image supplied with --image	Builds or retags, pushes, then deploys
--image	An image present in the local Docker daemon	Uses the local image; with --push-to, retags and pushes it
--image-uri	An image already present in your registry, identified by digest	Deploys that reference without local Docker acquisition work

For --image-uri, the reference prohibits combining --push-to, --image, -t or --remote. Keep the promotion invocation small. Removing a conflicting flag is appropriate only when the remaining command still describes the approved lane; it is not permission to replace promotion with a rebuild.

The following is an invocation template, not a command executed for this article. Replace the illustrative repository, digest placeholder and deployment ID with values from the approved promotion record. The placeholder is intentionally not a valid digest:

langgraph deploy --deployment-id DEPLOYMENT_ID --image-uri registry.example.com/agents/support@sha256:DIGEST_FROM_APPROVED_BUILD

The selected reference documents --deployment-id for updating an existing deployment and --image-uri for the already-pushed image. Authentication should come from the runtime’s established secret handling. Do not place a real key in a command example, promotion record or copied log. This guide does not require an account change or new credentials.

The deployment guide’s broad Docker prerequisite and the CLI installation page’s Docker instruction can appear inconsistent with this route. The detailed CLI section and merged implementation specifically establish no local Docker involvement for --image-uri. That exception concerns the promotion job. It does not remove Docker requirements from image building or prove the target cluster can pull the image.

Do not translate these Python deployment examples into JavaScript syntax by assumption. The selected reference presents deployment under the Python interface, even though it documents JavaScript equivalents for other commands. Confirm another client’s actual support before adding it to the release lane.

Inspect listeners before creating the deployment

The merged listener change added visibility without changing default placement. Its initial proposal would have selected the sole listener in self-hosted environments. Review reverted that behavior because blank placement already means deployment to the bundled operator. A workspace can have both a bundled operator and one configured listener; one listener therefore does not make the desired destination unambiguous.

Use the documented inspection command before preparing a creation request:

langgraph deploy listeners list

The reference says the listing includes listener IDs, their cluster identifier (compute_id) and Kubernetes namespaces. Treat it as inventory evidence. It does not prove that the listener is healthy, that its registry credentials work, or that the application has permission to use every listed namespace.

Follow this placement checklist:

1. Read the listener inventory from the already assigned workspace.
2. Match the intended cluster to the returned listener, using the inventory rather than an old copied ID.
3. Match the intended namespace to the listener’s supported namespaces.
4. State whether the target is a listener or the self-hosted bundled operator.
5. Put that decision into the creation review before submitting the deployment.

For Cloud listener-backed workspaces, the detailed reference says the CLI can select the sole listener and sole namespace. When there is a choice, it lists available placement options. Automation should resolve that choice deliberately rather than depend on an interactive prompt appearing in an unattended job.

For self-hosted deployments, leaving both placement inputs absent preserves the bundled-operator route. If a listener is intended, pass the supported placement inputs at creation. The important distinction is intent: an omitted value can be a meaningful choice, not a missing piece that the CLI will necessarily fill.

There is a documentation inconsistency worth keeping visible. The option table describes --listener-id and --k8s-namespace as creation options with --push-to; the merged image implementation says --image-uri shares that placement logic. The final listener implementation also narrows a broad sole-listener statement in the image PR: self-hosted blank placement still goes to the bundled operator. Verify the selected CLI version’s help and a canary creation before standardizing the combined image-and-placement invocation. Do not invent another placement flag to bridge the wording.

Freeze placement and check update compatibility

Listener and namespace are creation-time decisions. The CLI reference says they cannot change afterward and that both options are refused on an existing deployment. An update should identify the existing deployment and promote its next image while preserving its established placement. Moving execution location is a separate deployment decision, with its own review and cutover.

Before an update, use this compatibility table:

Existing state	Next action
Created with --image-uri and source is external_docker	Promote another approved digest through the compatible registry path
Created with --push-to and source is external_docker	The documented --image-uri path can update it
Created with another source type	Hold the registry-path update and plan a separately named deployment
Listener or namespace needs to change	Plan a new deployment and deliberate cutover
Source or placement is unknown	Recover the deployment record before submitting an update

The image PR and detailed reference establish that --push-to and --image-uri produce the same external_docker source and can update each other’s deployments. A general statement elsewhere that CLI updates can target deployments created through other methods should not be read as permission to convert every source to this registry type. The specific source check governs this route.

Name-based selection deserves care because the documented default deployment name comes from the current directory, and --name can find or create a deployment. For a known update, an explicit deployment ID makes the intended target easier to review. Keep the name as a label alongside the ID rather than making directory naming the only release control.

Separate placement migration from image rollback. A previous image digest may be reusable within the existing compatible deployment; it does not undo a mistaken choice of listener made when a new deployment was created. Establish the cutover and retirement plan before creating a replacement. Preserve the old deployment’s evidence until the replacement passes verification.

Maintain one promotion record per attempt

A command transcript alone is a weak release receipt. It can show what was requested while omitting which tests passed, which placement was intended, and which revision ultimately served the application. Build a record that joins those facts without claiming the CLI creates this schema.

Use these fields as an editorial template:

Record field	Evidence to retain
Artifact	Full registry image reference, source revision and build job identity
Test approval	Check results tied to that artifact and named approver or approved gate
Destination	Workspace, deployment ID and deployment name
Source compatibility	Evidence that the existing deployment uses external_docker
Placement	Intended listener and namespace, or explicit bundled-operator decision
Attempt	CLI version, submitted operation, timestamp and sanitized output
Result	Resulting revision, observed status and runtime evidence
Application check	Test input, expected outcome, actual outcome and approval to widen traffic
Recovery	Previously approved digest and the owner of the recovery decision

Give each attempt its own record, including failures. If a retry changes the image, deployment identity or placement plan, it is a different attempt rather than a continuation hidden under the same success label. Preserve the reason for the change so an incident reviewer can reconstruct the decision.

Keep secrets out of retained output and reference the approved secret version by its nonsecret identifier when configuration evidence needs it. A digest cannot capture runtime secret changes. Record relevant configuration differences separately so that two deployments of the same image are not falsely described as identical operating environments.

The operating-layer connection is evidence continuity: fleet replay asks for the trace needed to reconstruct agent work. Promotion adds another boundary to that trace, joining the agent-produced change, tested artifact and deployed revision. Environment readiness belongs in the pre-prompt readiness guide; keep this receipt focused on promotion rather than duplicating its setup checklist.

Verify the revision before widening traffic

Treat successful submission as the start of verification. The Cloud deployment guide says provisioning is queued. The CLI also offers --no-wait; choosing it removes a waiting step, not the need to establish a working result. A promotion should remain pending until deployment state, revision identity and application behavior are checked.

Use the documented read commands as evidence collection templates:

langgraph deploy list
langgraph deploy revisions list DEPLOYMENT_ID --limit 5
langgraph deploy logs --deployment-id DEPLOYMENT_ID --revision-id REVISION_ID --type deploy --limit 100

These examples use options present in the selected CLI reference. The revision listing helps identify the resulting revision; runtime logs can be scoped to it. Do not assume a displayed status or log line exposes every image or placement field needed by your receipt. Where necessary, obtain the remaining evidence from the authorized deployment view and your own cluster inventory.

Complete verification in order:

1. Confirm the observed deployment ID matches the promotion record.
2. Identify the revision created by this attempt and check its reported deployment state.
3. Confirm the intended image and execution placement through the available authorized evidence.
4. Inspect revision-scoped runtime logs for startup failures and unexpected behavior.
5. Run an application-level smoke check using approved synthetic input.
6. Record the outcome and the decision to widen traffic, keep the canary, or recover.

The smoke check is an editorial procedure, not a new LangGraph CLI command. Give it a small, known task with an expected result, required permissions and a stop condition. Prefer a task that demonstrates the deployed graph can complete its intended path without touching production records. A basic health response alone cannot prove that dependencies, tool access and graph execution behave correctly.

Keep traffic changes under the existing release process. This evidence bank does not establish a CLI traffic-splitting or rollback command, so none is invented here. Likewise, replacing the image with a previously approved digest does not prove database or external side effects are reversible. Review those dependencies before choosing recovery.

Rehearse failure before making promotion routine

A useful canary proves the guardrails as well as the happy path. Run the following checks in an approved nonproduction deployment, then retain the findings with the CLI version:

Check	Required operator outcome
Handoff has only a mutable tag	Promotion stops until the approved digest is recovered
Test receipt names another digest	Promotion stops before submission
Existing deployment has another source type	Operator plans a new deployment rather than forcing conversion
Self-hosted destination has one listener plus a bundled operator	Creation review explicitly chooses which route is intended
Update includes creation-time placement inputs	Operator removes the attempted relocation and plans it separately
Submission succeeds but smoke check fails	Traffic remains constrained and recovery gets a named owner

Separate checks enforced by the CLI from checks enforced by your release process. Digest validation, incompatible image options and source compatibility are documented implementation behavior. Receipt matching, approval evidence and the traffic hold are proposed operating controls. Report what each layer actually demonstrated instead of attributing your entire release policy to one command.

Repeat the canary when upgrading the deployment CLI or changing the destination’s placement arrangement. The existing CLI upgrade canary guide supplies the wider drift practice; this guide adds the artifact and placement cases that matter to image promotion. Preserve the last known working version and receipt so the comparison has a concrete baseline.

Finish by handing another operator the record and asking them to identify the tested digest, intended execution location and verified revision without interviewing the author. If those answers require memory or an unsaved terminal, improve the record before making the lane routine. The durable release boundary is a reviewed artifact, a deliberate destination and evidence that the resulting application actually passed its check.

Sources

1. LangChain: langgraph-cli 0.4.33 release, October 7, 2026.
2. LangChain: merged implementation of --image-uri, PR #9222.
3. LangChain: merged listener-list implementation and preserved placement behavior, PR #9221.
4. LangChain: LangGraph CLI reference, fetched October 12, 2026.
5. LangChain: Create a Cloud deployment, fetched October 12, 2026.