Requesting a package version with upstream repositories

When a client (for example, npm) requests a package version from a CodeArtifact repository named my_repo that has multiple upstream repositories, the following can occur:

• If my_repo contains the requested package version, it is returned to the client.

• If my_repo does not contain the requested package version, CodeArtifact looks for it in my_repo's upstream repositories. If the package version is found, a reference to it is copied to my_repo, and the package version is returned to the client.

• If neither my_repo nor its upstream repositories contain the package version, an HTTP 404 Not Found response is returned to the client.

When you add upstream repositories using the create-repository or update-repository command, the order they are passed to the --upstreams parameter determines their priority when a package version is requested. Specify upstream repositories with --upstreams in the order that you want CodeArtifact to use when a package version is requested. For more information, see Upstream repository priority order.

The maximum number of direct upstream repositories allowed for one repository is 10. Because direct upstream repositories can also have direct upstream repositories of their own, CodeArtifact can search more than 10 repositories for package versions. The maximum number of repositories CodeArtifact looks in when a package version is requested is 25.

Package retention from upstream repositories

If a requested package version is found in an upstream repository, a reference to it is retained and is always available from the downstream repository. The retained package version is not affected by any of the following:

• Deleting the upstream repository.

• Disconnecting the upstream repository from the downstream repository.

• Deleting the package version from the upstream repository.

• Editing the package version in the upstream repository (for example, by adding a new asset to it).

Fetch packages through an upstream relationship

If a CodeArtifact repository has an upstream relationship with a repository that has an external connection, requests for packages not in the upstream repository are copied from the external repository. For example, consider the following configuration: a repository named repo-A has an upstream repository named repo-B. repo-B has an external connection to https://npmjs.com.

If npm is configured to use the repo-A repository, running npm install triggers the copying of packages from https://npmjs.com into repo-B. The versions installed are also pulled into repo-A. The following example installs lodash.

$ npm config get registry
https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/my-downstream-repo/
$ npm install lodash
+ lodash@4.17.20
added 1 package from 2 contributors in 6.933s

After running npm install, repo-A contains just the latest version (lodash 4.17.20) because that's the version that was fetched by npm from repo-A.

aws codeartifact list-package-versions --repository repo-A --domain my_domain \
            --domain-owner 111122223333 --format npm --package lodash

Example output:

{
    "package": "lodash",
    "format": "npm",
    "versions": [
        {
            "version": "4.17.15",
            "revision": "REVISION-1-SAMPLE-6C81EFF7DA55CC",
            "status": "Published"
        }
    ]
}

Because repo-B has an external connection to https://npmjs.com, all the package versions that are imported from https://npmjs.com are stored in repo-B. These package versions could have been fetched by any downstream repository with an upstream relationship to repo-B.

The contents of repo-B provide a way to see all the packages and package versions imported from https://npmjs.com over time. For example, to see all the versions of the lodash package imported over time, you can use list-package-versions, as follows.

aws codeartifact list-package-versions --repository repo-B --domain my_domain \
            --domain-owner 111122223333 --format npm --package lodash --max-results 5

Example output:

{
    "package": "lodash",
    "format": "npm",
    "versions": [
        {
            "version": "0.10.0",
            "revision": "REVISION-1-SAMPLE-6C81EFF7DA55CC",
            "status": "Published"
        },
        {
            "version": "0.2.2",
            "revision": "REVISION-2-SAMPLE-6C81EFF7DA55CC",
            "status": "Published"
        },
        {
            "version": "0.2.0",
            "revision": "REVISION-3-SAMPLE-6C81EFF7DA55CC",
            "status": "Published"
        },
        {
            "version": "0.2.1",
            "revision": "REVISION-4-SAMPLE-6C81EFF7DA55CC",
            "status": "Published"
        },
        {
            "version": "0.1.0",
            "revision": "REVISION-5-SAMPLE-6C81EFF7DA55CC",
            "status": "Published"
        }
    ],
    "nextToken": "eyJsaXN0UGFja2FnZVZlcnNpb25zVG9rZW4iOiIwLjIuMiJ9"
}

Package retention in intermediate repositories

CodeArtifact allows chaining upstream repositories. For example, repo-A can have repo-B as an upstream and repo-B can have repo-C as an upstream. This configuration makes the package versions in repo-B and repo-C available from repo-A.

When a package manager connects to repository repo-A and fetches a package version from repository repo-C, the package version will not be retained in repository repo-B. The package version will only be retained in the most-downstream repository, in this example, repo-A. It will not be retained in any intermediate repositories. This is also true for longer chains; for example if there were four repositories repo-A, repo-B, repo-C, and repo-D and a package manager connected to repo-A fetched a package version from repo-D, the package version would be retained in repo-A but not in repo-B or repo-C.

Package retention behavior is similar when pulling a package version from an external repository, except that the package version is always retained in the repository that has the external connection attached. For example, repo-A has repo-B as an upstream. repo-B has repo-C as an upstream, and repo-C also has npmjs.com configured as an external connection; see the followng diagram.

If a package manager connected to repo-A requests a package version, lodash 4.17.20 for example, and the package version is not present in any of the three repositories, it will be fetched from npmjs.com. When lodash 4.17.20 is fetched, it will be retained in repo-A as that is the most-downstream repository and repo-C as it has the external connection to npmjs.com attached. lodash 4.17.20 will not be retained in repo-B as that is an intermediate repository.