How to Push and Version Docker Images in Amazon ECR for AI Deployments

A Docker image may be tested and ready on a developer workstation, but a local tag such as document-insight-api:1.0.0 is not yet a controlled production artifact. AWS runtimes need a private, durable image location, deployment teams need an immutable identity, and security teams need scanning and audit evidence.

This guide pushes the synthetic document-insight-api image to a private Amazon Elastic Container Registry (Amazon ECR) repository. It applies an immutable release tag and source-revision tag, records the registry digest, reviews vulnerability results, and shows how staging and production should reference the same approved digest.

The workflow works for containerized AI APIs that call Amazon Bedrock or SageMaker, and for applications that run approved models inside the container. Model identity is tracked separately from the container version so that teams can tell whether a release changed code, model behavior, or both.

What You Will Build

The completed workflow provides:

• A private ECR repository named document-insight-api.

  
  

• Immutable image tags for releases and source revisions.

  
  

• A narrowly scoped IAM role that can push only to the intended repository.

  
  

• Short-lived Docker authentication to the selected ECR registry.

  
  

• Two human-readable tags pointing to the same pushed manifest.

  
  

• A recorded SHA-256 image digest used by deployments.

  
  

• Basic or enhanced vulnerability scanning selected at the registry level.

  
  

• A promotion and rollback process that never rebuilds or overwrites an approved release.

The release flow is:

Locally verified Docker image
        ↓
Release tag + source-revision tag
        ↓
Authenticated push to private Amazon ECR
        ↓
Digest, scan, and optional signature verification
        ↓
Staging deployment by digest
        ↓
Production approval
        ↓
Production deployment of the same digest

Why Tags Alone Are Not Enough

A Docker tag is a readable name associated with an image manifest. In a mutable repository, the same tag can later point to different content. That makes a tag such as latest or prod a poor audit identity: two people can use the same deployment instruction at different times and receive different images.

An image digest is content-addressed. A reference such as:

<ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/document-insight-api@sha256:<DIGEST>

identifies a specific image manifest. Tags remain useful for discovery and release management, but the digest is the authoritative deployment identity.

For AI systems, the distinction is especially important. Application code may remain unchanged while a model identifier, prompt package, tokenizer, or embedded model artifact changes. The release record must identify each relevant component instead of treating one convenient tag as the complete system version.

Target Architecture

Amazon ECR stores the image and its metadata. Amazon ECR basic scanning or Amazon Inspector enhanced scanning evaluates vulnerabilities according to the organization’s registry configuration. Optional managed signing can create signatures when images are pushed. The deployment runtime—such as Amazon ECS or Amazon EKS—pulls the approved image by digest.

Prerequisites

Prepare the following:

• Docker Desktop or Docker Engine running with the verified local image document-insight-api:1.0.0.

  
  

• AWS CLI configured with short-lived credentials for the intended AWS account.

  
  

• Permission to create or use the document-insight-api ECR repository.

  
  

• Permission to obtain an ECR authorization token and push to that repository.

  
  

• Region ap-south-1, or another deliberately selected Region used consistently throughout the workflow.

  
  

• The reviewed Git commit identifier used to build the local image.

  
  

• A defined vulnerability policy and owner for release exceptions.

  
  

• Optional: an AWS Signer profile and managed-signing rule.

  
  

Use a sandbox or development AWS account for the first implementation. Do not publish a real account ID, registry URI, private repository policy, or credential output in the article screenshots.

Step 1: Define the Image Versioning Contract

Decide what each identifier means before pushing anything. Use this contract for the tutorial:

Identifier	Example	Purpose	Mutable?
Release tag	1.0.0	Human-readable application release	No
Source tag	git-a1b2c3d4e5f6	Maps the image to one reviewed commit	No
ECR digest	sha256:...	Canonical deployment identity	Content-addressed
Model ID	synthetic-summary-v1	Identifies model or inference configuration	Managed separately
Environment	staging or prod	Deployment configuration, not image content	Managed outside image

Do not use latest, staging, or prod as the only deployment identity. Those names describe selection or environment state, not image content. If an operational alias is unavoidable, keep it outside the production release contract and make sure the underlying digest remains visible and approved.

The image should also contain OCI labels created during the build:

org.opencontainers.image.version=1.0.0
org.opencontainers.image.revision=<FULL_GIT_COMMIT_SHA>
org.opencontainers.image.source=<VERIFIED_REPOSITORY_URL>

If a model is embedded in the image, record its version, source, license, and checksum in release metadata. If the application calls a managed model endpoint, store the approved model identifier and inference configuration in the deployment record rather than pretending they are part of the image digest.

Step 2: Confirm the Local Image Is the Release Candidate

Verify the local image before it enters the registry:

docker image inspect document-insight-api:1.0.0 --format '{{.Id}}'
docker image inspect document-insight-api:1.0.0 --format '{{json .Config.Labels}}'
docker image inspect document-insight-api:1.0.0 --format '{{json .Config.User}}'
docker scout quickview document-insight-api:1.0.0

Confirm that:

• Unit, integration, health, and applicable AI-behavior tests passed.

  
  

• The source-revision label matches the reviewed commit.

  
  

• The image runs as the intended non-root user.

  
  

• No secrets, customer data, model credentials, or private build files are present.

  
  

• The local vulnerability result meets the pre-push policy.

  
  

• The image platform matches the target AWS runtime.

  
  

Do not rebuild the image between local approval and ECR push. Tag and push the already verified content. If remediation changes a base image, dependency, model file, or application layer, treat the result as a new release candidate and repeat validation.

Step 3: Create a Private ECR Repository With Release Controls

In the Amazon ECR console, select the target Region, open Private repositories, and create document-insight-api.

Use these settings:

Repository control	Tutorial decision	Production reason
Visibility	Private	Prevent anonymous image access
Tag behavior	Immutable	Prevent release tags from being overwritten
Immutability exclusions	None for release repository	Keep every pushed release tag fixed
Encryption	Organization-approved AES-256 or AWS KMS option	Protect repository data at rest
Scanning	Registry-level basic scan-on-push or enhanced scanning	Detect known package vulnerabilities
Resource tags	Application, owner, environment scope, cost center	Ownership and governance
Lifecycle policy	Add after defining retention and rollback needs	Control storage without deleting active releases

Choose encryption deliberately. AWS documentation states that an existing repository’s encryption setting cannot be changed; a different encryption choice requires a new repository and a controlled image migration.

Amazon ECR supports immutable repositories as well as immutability exclusion patterns. Exclusions are useful for specific workflows, but this release repository does not need a movable latest tag. The current repository creation guidance also recommends configuring scanning at the private-registry level so filters can consistently select repositories for basic or enhanced scanning.

Step 4: Grant Push Access to One Repository

Use an IAM Identity Center role for a person or a workload role for CI. Do not use root credentials or embed long-lived AWS keys in Docker configuration, the repository, or pipeline variables.

The push identity needs ecr:GetAuthorizationToken plus layer and manifest operations on the named repository. A scoped policy follows this pattern:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GetEcrAuthorizationToken",
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    },
    {
      "Sid": "PushDocumentInsightImage",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:CompleteLayerUpload",
        "ecr:InitiateLayerUpload",
        "ecr:PutImage",
        "ecr:UploadLayerPart"
      ],
      "Resource": "arn:aws:ecr:<AWS_REGION>:<ACCOUNT_ID>:repository/document-insight-api"
    }
  ]
}

Replace placeholders during implementation and never publish the real ARN. Repository administration, tag-mutability changes, lifecycle-policy changes, deletion, and broad pull access are separate permissions and are not required merely to push an approved image.

AWS provides the required repository-scoped action list in its ECR push IAM guidance. If managed signing is enabled, grant only the additional AWS Signer permission and signing profile required by that rule.

Step 5: Authenticate Docker to the Correct ECR Registry

Set non-secret variables in PowerShell:

$AwsRegion = 'ap-south-1'
$Repository = 'document-insight-api'
$ReleaseTag = '1.0.0'
$CommitSha = (git rev-parse --short=12 HEAD).Trim()
if ($LASTEXITCODE -ne 0) { throw 'Unable to resolve the Git commit.' }
$CommitTag = "git-${CommitSha}"
$AwsAccountId = aws sts get-caller-identity --query Account --output text
$Registry = "${AwsAccountId}.dkr.ecr.${AwsRegion}.amazonaws.com"
$RemoteRepository = "${Registry}/${Repository}"

Verify that the active AWS identity, account, Region, and repository are correct before authenticating:

aws sts get-caller-identity
aws ecr describe-repositories --region $AwsRegion --repository-names $Repository

Authenticate without printing or storing the password:

aws ecr get-login-password --region $AwsRegion | docker login --username AWS --password-stdin $Registry

Amazon ECR authorization tokens are valid for 12 hours and are obtained per registry. A successful login does not prove the identity is authorized to push to every repository. The repository policy and IAM identity still determine what operations are allowed. See the official ECR push workflow.

If Docker reports no basic auth credentials or an HTTP 403 response, first check token expiry, Region consistency, registry URI, and repository-scoped IAM permissions. Do not solve an authentication problem by granting full ECR administration.

Step 6: Apply Immutable Tags and Push the Image

Add the release and source-revision tags to the same local image:

docker tag document-insight-api:1.0.0 "${RemoteRepository}:${ReleaseTag}"
docker tag document-insight-api:1.0.0 "${RemoteRepository}:${CommitTag}"

Confirm that both remote tags reference the same local image ID:

docker image inspect "${RemoteRepository}:${ReleaseTag}" --format '{{.Id}}'
docker image inspect "${RemoteRepository}:${CommitTag}" --format '{{.Id}}'

Push both tags:

docker push "${RemoteRepository}:${ReleaseTag}"
docker push "${RemoteRepository}:${CommitTag}"

The second push should reuse existing layers and add another tag to the same manifest. Capture the digest reported by the push output, but verify it from ECR in the next step.

Do not use docker push --all-tags in a controlled release unless every local tag has been reviewed. A developer workstation may contain experimental or unapproved tags that should never enter the production registry.

Step 7: Verify the Digest, Scan, and Optional Signature

Query ECR rather than trusting only local tag state:

aws ecr describe-images `
  --region $AwsRegion `
  --repository-name $Repository `
  --image-ids imageTag=$ReleaseTag `
  --query 'imageDetails[0].{Digest:imageDigest,Tags:imageTags,PushedAt:imagePushedAt,Size:imageSizeInBytes}' `
  --output table

Resolve the immutable deployment URI:

$ImageDigest = aws ecr describe-images `
  --region $AwsRegion `
  --repository-name $Repository `
  --image-ids imageTag=$ReleaseTag `
  --query 'imageDetails[0].imageDigest' `
  --output text

$PinnedImage = "${RemoteRepository}@${ImageDigest}"
$PinnedImage

Query the source tag as well and confirm it resolves to the same digest. Do not compare the local Docker image ID directly with the ECR manifest digest as though they were the same object; use the ECR-reported manifest digest as the registry and deployment identity.

Wait for the configured scan to complete:

• Basic scanning: review the Amazon ECR scan findings for the pushed image.

  
  

• Enhanced scanning: review Amazon Inspector coverage and findings for the repository and digest.

Basic scanning detects supported operating-system package vulnerabilities. Enhanced scanning through Amazon Inspector adds broader package coverage and continuous or scan-on-push options, depending on registry configuration. Review Amazon Inspector ECR scanning and its pricing before selecting the organization-wide mode.

If ECR managed signing is enabled, confirm the signing status for this digest and retain the signature evidence. Amazon ECR’s current managed-signing documentation describes automatic AWS Signer signatures created as images are pushed.

Step 8: Promote and Roll Back by Digest

Deploy the digest to staging:

<ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/document-insight-api@sha256:<APPROVED_DIGEST>

Run the staging smoke, integration, security, and AI-behavior tests. The release record should contain:

Application release: 1.0.0
Source revision:      <FULL_GIT_COMMIT_SHA>
ECR digest:           sha256:<APPROVED_DIGEST>
Model identifier:     synthetic-summary-v1
Prompt/config version:<VERSION_OR_CHECKSUM>
SBOM:                 <ARTIFACT_REFERENCE>
Scan decision:        <RESULT_AND_EXCEPTION_REFERENCE>

After approval, production must reference the same digest. Do not rebuild the image, move a prod tag, or retag different content during promotion.

Rollback follows the same rule: update the deployment to a previously approved digest and create a new deployment event. Do not overwrite 1.0.0 to make it point to the prior release. Immutable release history is more valuable than making a tag appear current.

For multi-architecture images, the deployed digest may identify a manifest list whose child manifests represent linux/amd64, linux/arm64, or other platforms. Verify each built platform and record the top-level digest used by the runtime. Amazon ECR documents multi-architecture manifest pushes.

Verify the Complete ECR Workflow

Test both successful behavior and the controls intended to stop unsafe changes:

Control	Test	Expected result
Repository configuration	Describe repository and registry scan settings	Correct Region, immutability, encryption, and scan coverage
Scoped push	Push using the approved role	Only document-insight-api accepts the push
Unauthorized push	Use a role without repository push access	ECR denies layer or manifest upload
Version traceability	Query both tags	Release and commit tags resolve to the same digest
Tag immutability	Attempt to replace a disposable existing tag with different content	ECR rejects the overwrite
Scan gate	Review final digest findings	Result meets policy or has an approved, expiring exception
Digest pull	Pull the image by digest in a clean test environment	Pulled image passes the smoke test
Promotion integrity	Compare staging and production definitions	Both use the same approved digest
Rollback	Deploy a previous approved digest in a sandbox	Runtime changes without rewriting release tags
Auditability	Correlate role, push, digest, scan, approval, and deployment	One evidence chain identifies the release

Perform the overwrite and unauthorized-access tests with disposable tags and non-production roles. Do not attack a shared production workflow merely to obtain evidence.

These checks prove registry identity, access behavior, and promotion integrity for the tested path. They do not prove application quality, model safety, runtime isolation, or regulatory compliance.

Production Considerations

Tag and Digest Governance

Keep a small, documented tag vocabulary. Release and source tags should be immutable. Store environment promotion in deployment configuration or a release database rather than moving tags. Require every deployment record to include the resolved digest.

If the organization uses ECR immutability exclusions for development aliases, keep those patterns out of production release repositories or protect them with separate policies. An exclusion restores mutability for matching tags and therefore changes their audit meaning.

AI Model and Configuration Versioning

Container, model, prompt, retrieval index, and runtime configuration often have independent lifecycles. Record them independently:

• Image digest identifies packaged application content.

  
  

• Managed-model ID or endpoint configuration identifies inference behavior.

  
  

• Embedded model checksum identifies the packaged model artifact.

  
  

• Prompt/config checksum identifies behavioral configuration.

  
  

• Evaluation dataset and threshold versions identify the release gate.

  
  

Do not encode every field into one unreadable Docker tag. Use labels and release metadata while keeping the digest authoritative.

IAM, Repository Policies, and Network Access

Separate repository administration, image push, image pull, scanning, signing, and deletion permissions. Runtime roles usually need pull access, not push access. CI roles should not be able to alter tag immutability, encryption, lifecycle policies, or repository policies.

For private networks, evaluate ECR API and Docker registry VPC endpoints, Amazon S3 access required for image layers, DNS, endpoint policies, and first-pull behavior. Test the exact network path used by the production runtime.

Scanning, Signing, and Release Gates

Scan locally for fast feedback and scan again in ECR. Vulnerability data changes over time, so continuously reassess deployed digests. Define how severity, exploitability, fix availability, ownership, and exception expiry affect promotion.

For stronger provenance, evaluate ECR managed signing with AWS Signer and verify signatures at deployment. ECR supports managed verification integration for Amazon EKS and a lifecycle-hook pattern for Amazon ECS; select and test the mechanism appropriate to the runtime.

A signature confirms origin and integrity under the signing policy. It does not prove that the application is safe, vulnerability-free, or approved for a particular dataset.

Multi-Account and Multi-Region Distribution

Use separate AWS accounts for development, staging, and production where the organization requires stronger boundaries. Consider a central build or registry account with controlled replication to workload accounts and Regions. Restrict which principals can replicate, pull, or deploy each repository namespace.

Replication creates additional copies and transfer activity. Confirm that target-account encryption, scanning, signing, lifecycle, and retention behavior meet the same release requirements.

Lifecycle and Rollback Retention

Create lifecycle rules only after defining rollback, investigation, retention, and legal requirements. Preview the rule before applying it. AWS notes that eligible images can be expired or archived within 24 hours after meeting lifecycle criteria and that lifecycle actions appear in CloudTrail.

Protect currently deployed digests and the minimum rollback set. Clean up untagged build artifacts, abandoned branch images, and superseded development versions according to policy. Signatures, SBOMs, and other OCI reference artifacts must remain aligned with the subject image lifecycle.

Monitoring and Auditability

Correlate:

Source commit
→ CI build and tests
→ local image evidence
→ ECR push identity and time
→ release tags and digest
→ scan/signing decision
→ approval record
→ staging and production deployment revision

Use CloudTrail, registry events, Amazon Inspector/EventBridge integrations, and deployment logs according to the organization’s audit design. Avoid putting credentials, internal registry URIs, or customer data in public screenshots and logs.

Cost

Amazon ECR costs can include stored image and reference-artifact data, transfer to some destinations, cross-Region replication, AWS KMS use, enhanced scanning through Amazon Inspector, and managed signing. Large AI images and duplicated model layers can materially increase storage and rollout time.

Use lifecycle policies carefully, keep runtime and model layers focused, and review the current Amazon ECR pricing and related service pricing before publication and rollout. Do not hardcode a cost estimate without the Region, image volume, scan mode, retention, replication, and transfer assumptions.

Clean Up the Tutorial Resources

Preserve the digest, scan result, optional signature, two screenshots, and any audit evidence required for the article before cleanup.

Then:

1. Stop any sandbox ECS tasks, EKS workloads, or other deployments that reference the tutorial digest.

   
   

2. Remove the local remote tags if they are no longer needed.

   
   

3. Log Docker out of the tutorial registry with docker logout <REGISTRY_HOST>.

   
   

4. Delete only the disposable ECR tags or image digest after confirming no deployment, rollback plan, SBOM, or signature still depends on them.

   
   

5. Preview lifecycle-policy effects before applying or changing cleanup rules.

   
   

6. Delete the ECR repository only if it was created solely for the tutorial and all required evidence has been retained.

   
   

7. Remove dedicated push roles, policies, signing rules, replication rules, alarms, and KMS resources only after checking for other consumers.

   
   

Repository deletion and image deletion are destructive. Do not use a forced repository deletion command against a shared or production repository.

Reference Implementation

This tutorial can reuse the container repository from the production Docker image article:

aws-production-ai-container/
├── README.md
├── Dockerfile
├── app/
├── tests/
├── scripts/
│   ├── verify-image.ps1
│   ├── push-ecr.ps1
│   └── verify-ecr-digest.ps1
├── policies/
│   └── ecr-push-policy.json
└── infrastructure/
    ├── ecr.yml
    └── lifecycle-policy.json

How Codersarts Can Help

Codersarts can design and implement a controlled AWS image supply chain, including production Docker builds, private ECR repositories, tag and digest governance, least-privilege CI roles, vulnerability gates, managed signing, multi-account promotion, ECS or EKS deployment, rollback, and audit correlation.

Learn more about Codersarts AI development services or discuss how to move a containerized AI prototype into a traceable AWS deployment workflow.

Conclusion

Amazon ECR turns a locally verified Docker image into a controlled AWS deployment artifact only when identity and governance are explicit. Immutable release and source tags help people find the image, while the ECR digest identifies the exact manifest that staging tested and production approved.

Push once, scan and optionally sign that content, promote the same digest, and roll back by selecting an earlier approved digest. That approach keeps container code, AI model configuration, security evidence, and deployment history understandable as the system evolves.

References

• Create an Amazon ECR private repository

• IAM permissions for pushing to a private ECR repository

• Push a Docker image to Amazon ECR

• Prevent ECR image tags from being overwritten

• View image details in Amazon ECR

• Scan ECR images with Amazon Inspector

• Amazon ECR managed signing

• Verify Amazon ECR image signatures

• Push a multi-architecture image to Amazon ECR

• Amazon ECR lifecycle policies

• Amazon ECR pricing