Lesson 360 · AWS Learning Path

AWS 360: CodeArtifact domains, repositories, upstreams, retention, and permissions

Anil Jalela · Published Jun 20, 2026 · 6 min read

Why this lesson matters

Package repositories sit inside the software supply chain. One wrong upstream, overly broad publisher, mutable version practice, or leaked authorization token can compromise many builds. CodeArtifact controls package distribution, but teams still own naming, dependency locks, provenance, vulnerability response, retention, and cache cleanup.

Resource model

AWS account/Region
  -> domain (storage/deduplication/KMS boundary)
     -> repository (consumer/publisher policy and upstream order)
        -> package group/namespace/package
           -> version/revision/assets/status/origin

A domain stores package assets once and lets repositories reference them. Repositories expose package-manager endpoints and ordered upstreams. External connections attach supported public repositories through one CodeArtifact repository; downstream repositories can reach them through upstream relationships.

Architecture decisions

Choose account, Region, domain, repositories, and ownership from blast radius and lifecycle. A common pattern separates quarantine/intake, approved shared packages, team publishing, and production consumption. More repositories add policy/operations; one repository can mix trust levels.

Define package format, namespace ownership, internal-name reservation, publisher identity, consumer identity, upstream priority, public source policy, approval promotion, retention, incident revocation, and cost allocation.

Upstream resolution and retention

When a requested version is absent locally, CodeArtifact searches direct upstreams in configured priority order and their reachable graph, then an external source where configured. Current quotas allow up to 10 direct upstreams and a search of up to 25 repositories; verify current quotas for the Region.

When a package is fetched from an upstream, a reference is retained downstream. It can remain available even if the upstream relationship/repository/version later changes or disappears. This improves repeatability but means removing an upstream does not purge retained vulnerable content.

Draw exact resolution order and test duplicate names/versions. Do not assume the public package manager chooses the source you intended.

Origin controls and dependency substitution

Package versions can enter through direct publish, internal upstream, or external upstream. Package and package-group origin controls restrict these paths. Package-group controls can allow, block, or allow only named repositories for publish, external upstream, and internal upstream.

For internally authored namespaces, allow publishing only from controlled publisher repositories/roles and block public ingestion. For approved public groups, block direct internal publishing where appropriate and permit external intake only through controlled repositories. Existing older packages may need explicit review rather than reliance on defaults.

Reserve names before attackers can publish matching public packages. Lock exact versions and hashes, review package origin and assets, and prevent build tools from silently falling back directly to public registries.

Package versions and lifecycle

Understand statuses:

Deletion removes the package version record and can permit republishing. Disposal is irreversible for assets. Neither action removes copies from developer caches, CI caches, images, downstream references, or released applications.

Use a lifecycle state machine: intake, scan, approve, publish/promote, deprecate/unlist, quarantine/archive, retention decision, dispose/delete. Require owner, reason, affected-build analysis, backup/evidence policy, and approval before irreversible disposal.

Authentication and authorization

Clients generally obtain a short-lived authorization token through AWS credentials, then configure the package manager endpoint. Do not commit tokens or print login commands with tokens in logs. CI should use a workload role; developer access should use federation/Identity Center.

Authorization can involve identity policy, domain resource policy, repository resource policy, STS token permission, KMS authorization, and package-resource actions. Separate:

• domain administration and policy/KMS ownership;
• repository/upstream configuration;
• package publishing;
• package consumption;
• status change/disposal;
• audit/security investigation.

Cross-account access needs both appropriate resource/identity authorization and KMS path. Deny publishing from ordinary consumer roles.

Integrity and promotion

For every package record source repository/commit, clean status, build ID/image, dependency lock, tests, SBOM, package coordinates, version revision, asset hashes, signature/attestation, publisher role/session, approval, and destination repositories.

Do not rebuild to promote. Copy the same reviewed version/assets using supported workflow and verify hashes. Prevent republishing the same semantic version with different bytes through policy/process and alerting.

Read-only inventory

aws codeartifact list-domains --region ap-south-1
aws codeartifact list-repositories --region ap-south-1
aws codeartifact describe-domain --domain DOMAIN --region ap-south-1
aws codeartifact describe-repository --domain DOMAIN --repository REPOSITORY --region ap-south-1
aws codeartifact list-packages --domain DOMAIN --repository REPOSITORY --region ap-south-1

Use authorized placeholders and pagination. Do not call get-authorization-token merely for inventory because it creates usable credential material. Redact names, owners, KMS keys, endpoints, package coordinates, policies, and account IDs.

Network, availability, and caching

Builds need DNS/TLS and routes to CodeArtifact endpoints plus STS for token acquisition and any upstream dependencies. Private builds require designed NAT/endpoints and policy. Repository availability does not guarantee public upstream availability for a not-yet-retained version.

Define offline/emergency behavior: approved retained dependencies, controlled cache, no silent source fallback, expiry/validation, and restoration. Cache keys include lock and platform/runtime identity. Scan both new intake and retained inventory as intelligence changes.

Package-format and regional boundaries

Package ecosystems do not express identity and immutability identically. Maven coordinates include group, artifact, and version and can contain multiple assets; npm uses scopes and package/version semantics; Python packages can publish multiple distributions for one version; NuGet and Swift have their own client and metadata behavior; generic packages expose explicit namespace/package/version/assets. Design naming, expected assets, checksum verification, and completion tests per format rather than assuming one universal “package file.”

CodeArtifact domains and repositories are Regional. A second Region is a separate distribution and operating decision, not an automatic replica of the first repository. If resilience or residency requires multi-Region package availability, define how approved immutable versions and provenance are copied, how consumers select a Region, how origin controls remain equivalent, and how conflicting publication is prevented. Test primary-Region and external-upstream outages before claiming build continuity.

Package-manager configuration also matters. Ensure the approved endpoint is the only configured source for controlled builds, verify TLS and repository identity, and fail closed when it is unavailable. A fallback directly to a public registry can bypass retained evidence, origin policy, malware review, and incident quarantine.

Cost and quotas

Model storage, requests, upstream transfer, build download volume, Regions/accounts, logs/scanning, KMS, network transfer/endpoints, and operator time. Retention saves external availability but consumes storage. Use unit costs such as cost per build/package/team and alert on unusual publish/download patterns.

Incident exercise

Handle ten cases: internal name appears publicly; malicious version retained downstream; publisher token leaks; consumer role can publish; KMS policy blocks builds; upstream order changes resolution; vulnerable version exists in caches/releases; package archived during critical build; disposal requested without evidence; external registry outage affects a new dependency.

For each state package/revision/assets, affected builds/releases, containment, origin block, token/session response, cache/image search, replacement, evidence, communication, and retest.

Acceptance

Submit domain/repository/upstream graph, namespace/origin policy, IAM/resource/KMS flow, token handling, promotion/provenance, lifecycle/retention state machine, network path, cost/quota model, monitoring, ten incident records, and migration/cleanup.

Pass requires no static package token, publisher/consumer separation, dependency-substitution protection, complete upstream order, immutable asset evidence, cache-aware revocation, and explicit approval for irreversible disposal.

Official sources

• CodeArtifact concepts
• Upstream behavior and retention
• Package group origin controls
• Package origin controls
• Package version status
• CodeArtifact authentication and tokens