Update package version status

Every package version in CodeArtifact has a status that describes the current state and availability of the package version. You can change the package version status using both the AWS CLI and the console.

Note

For more information on package version status, including a list of the available statuses, see Package version status.

Updating package version status

Setting the status of a package version allows controlling how a package version can be used without deleting it completely from the repository. For example, when a package version has a status of Unlisted, it can still be downloaded as normal, but it will not appear in package version lists returned to commands such as npm view. The UpdatePackageVersionsStatus API allows setting the package version status of multiple versions of the same package in a single API call. For a description of the different statuses, see Packages overview.

Use the update-package-versions-status command to change the status of a package version to Published, Unlisted, or Archived. To see the required IAM permissions to use the command, see Required IAM permissions to update a package version status. The following example sets the status of version 4.1.0 of the npm package chalk to Archived.

aws codeartifact update-package-versions-status --domain my_domain
 --domain-owner 111122223333 --repository my_repo --format npm --package chalk 
--versions 4.1.0 --target-status Archived

Sample output:

{
    "successfulVersions": {
        "4.1.0": {
            "revision": "+Oz8skWbwY3k8M6SrNIqNj6bVH/ax+CxvkJx+No5j8I=",
            "status": "Archived"
        }
    },
    "failedVersions": {}
}

This example uses an npm package, but the command works identically for other formats. Multiple versions can be moved to the same target status using a single command, see the following example.

aws codeartifact update-package-versions-status --domain my_domain
 --domain-owner 111122223333 --repository my_repo --format npm --package chalk 
--versions 4.1.0 4.1.1 --target-status Archived

Sample output:

{
    "successfulVersions": {
        "4.1.0": {
            "revision": "25/UjBleHs1DZewk+zozoeqH/R80Rc9gL1P8vbzVMJ4=",
            "status": "Archived"
        },
        "4.1.1": {
            "revision": "+Oz8skWbwY3k8M6SrNIqNj6bVH/ax+CxvkJx+No5j8I=",
            "status": "Archived"
        }
    },
    "failedVersions": {}
}

Note that once published, a package version cannot be moved back to the Unfinished state, so this status is not permitted as a value for the --target-status parameter. To move the package version to the Disposed state, use the dispose-package-versions command instead as described below.

Required IAM permissions to update a package version status

To call update-package-versions-status for a package, you must have the codeartifact:UpdatePackageVersionsStatus permission on the package resource. This means you can grant permission to call update-package-versions-status on a per-package basis. For example, an IAM policy that grants permission to call update-package-versions-status on the npm package chalk would include a statement like the following.

{
  "Action": [
    "codeartifact:UpdatePackageVersionsStatus"
  ],
  "Effect": "Allow",
  "Resource": "arn:aws:codeartifact:us-east-1:111122223333:package/my_domain/my_repo/npm//chalk"
}

Updating status for a scoped npm package

To update the package version status of an npm package version with a scope, use the --namespace parameter. For example, to unlist version 8.0.0 of @nestjs/core, use the following command.

aws codeartifact update-package-versions-status --domain my_domain
 --domain-owner 111122223333 --repository my_repo --format npm --namespace nestjs 
--package core --versions 8.0.0 --target-status Unlisted

Updating status for a Maven package

Maven packages always have a group ID, which is referred to as a namespace in CodeArtifact. Use the --namespace parameter to specify the Maven group ID when calling update-package-versions-status. For example, to archive version 2.13.1 of the Maven package org.apache.logging.log4j:log4j, use the following command.

aws codeartifact update-package-versions-status --domain my_domain
 --domain-owner 111122223333 --repository my_repo --format maven 
--namespace org.apache.logging.log4j --package log4j 
--versions 2.13.1 --target-status Archived

Specifying a package version revision

A package version revision is a string that specifies a specific set of assets and metadata for a package version. You can specify a package version revision to update the status of package versions that are in a specific state. To specify a package version revision, use the --version-revisions parameter to pass one or more comma-separated package versions and the package version revision pairs. The status of a package version will only be updated if the current revision of the package version matches the value specified.

Note

The —-versions parameter must also be defined when using the --version-revisions parameter.

aws codeartifact update-package-versions-status --domain my_domain 
   --domain-owner 111122223333 --repository my_repo --format npm --package chalk 
   --version-revisions "4.1.0=25/UjBleHs1DZewk+zozoeqH/R80Rc9gL1P8bzVMJ4=" 
   --versions 4.1.0 --target-status Archived

To update multiple versions with a single command, pass a comma-separated list of version and version revision pairs to the --version-revisions options. The following example command defines two different package version and package version revision pairs.

aws codeartifact update-package-versions-status --domain my_domain 
 --domain-owner 111122223333 --repository my_repo --format npm 
 --package chalk
 --version-revisions "4.1.0=25/UjBleHs1DZewk+zozoeqH/R80Rc9gL1P8vbzVMJ4=,4.0.0=E3lhBp0RObRTut4pkjV5c1AQGkgSA7Oxtil6hMMzelc="  
 --versions 4.1.0 4.0.0 --target-status Published

Sample output:

{
    "successfulVersions": {
        "4.0.0": {
            "revision": "E3lhBp0RObRTut4pkjV5c1AQGkgSA7Oxtil6hMMzelc=",
            "status": "Published"
        },
        "4.1.0": {
            "revision": "25/UjBleHs1DZewk+zozoeqH/R80Rc9gL1P8vbzVMJ4=",
            "status": "Published"
        }
    },
    "failedVersions": {}
}

When updating multiple package versions, the versions passed to --version-revisions must be the same as the versions passed to --versions. If a revision is specified incorrectly, that version will not have its status updated.

Using the expected status parameter

The update-package-versions-status command provides the --expected-status parameter that supports specifying the expected current status of a package version. If the current status does not match the value passed to --expected-status, the status of that package version will not be updated.

For example, in my_repo, versions 4.0.0 and 4.1.0 of the npm package chalk currently have a status of Published. A call to update-package-versions-status that specifies an expected status of Unlisted will fail to update both package versions because of the status mismatch.

aws codeartifact update-package-versions-status --domain my_domain
--domain-owner 111122223333 --repository my_repo --format npm --package chalk 
--versions 4.1.0 4.0.0 --target-status Archived --expected-status Unlisted

Sample output:

{
    "successfulVersions": {},
    "failedVersions": {
        "4.0.0": {
            "errorCode": "MISMATCHED_STATUS",
            "errorMessage": "current status: Published, expected status: Unlisted"
        },
        "4.1.0": {
            "errorCode": "MISMATCHED_STATUS",
            "errorMessage": "current status: Published, expected status: Unlisted"
        }
    }
}

Errors with individual package versions

There are multiple reasons why the status of a package version will not be updated when calling update-package-versions-status. For example, the package version revision may have been specified incorrectly, or the expected status does not match the current status. In these cases, the version will be included in the failedVersions map in the API response. If one version fails, other versions specified in the same call to update-package-versions-status might be skipped and not have their status updated. Such versions will also be included in the failedVersions map with an errorCode of SKIPPED.

In the current implementation of update-package-versions-status, if one or more versions cannot have their status changed, all other versions will be skipped. That is, either all versions are updated successfully or no versions are updated. This behavior is not guaranteed in the API contract; in the future, some versions might succeed while other versions fail in a single call to update-package-versions-status.

The following example command includes an version status update failure caused by a package version revision mismatch. That update failure causes another version status update call to be skipped.

aws codeartifact update-package-versions-status --domain my_domain
  --domain-owner 111122223333 --repository my_repo 
  --format npm --package chalk 
  --version-revisions "4.1.0=25/UjBleHs1DZewk+zozoeqH/R80Rc9gL1P8vbzVMJ=,4.0.0=E3lhBp0RObRTut4pkjV5c1AQGkgSA7Oxtil6hMMzelc=" 
  --versions 4.1.0 4.0.0 --target-status Archived

Sample output:

{
    "successfulVersions": {},
    "failedVersions": {
        "4.0.0": {
            "errorCode": "SKIPPED",
            "errorMessage": "version 4.0.0 is skipped"
        },
        "4.1.0": {
            "errorCode": "MISMATCHED_REVISION",
            "errorMessage": "current revision: 25/UjBleHs1DZewk+zozoeqH/R80Rc9gL1P8vbzVMJ4=, expected revision: 25/UjBleHs1DZewk+zozoeqH/R80Rc9gL1P8vbzVMJ="
        }
    }
}

Disposing of package versions

The Disposed package status has similar behavior to Archived, except that the package assets will be permanently deleted by CodeArtifact so that the domain owner’s account will no longer be billed for the asset storage. For more information about each package version status, see Package version status. To change the status of a package version to Disposed, use the dispose-package-versions command. This capability is separate from update-package-versions-status because disposing of a package version is not reversible. Because the package assets will be deleted, the version’s status cannot be changed back to Archived, Unlisted, or Published. The only action that can be taken on a package version that has been disposed is for it to be deleted using the delete-package-versions command.

To call dispose-package-versions successfully, the calling IAM principal must have the codeartifact:DisposePackageVersions permission on the package resource.

The behavior of the dispose-package-versions command is similar to update-package-versions-status, including the behavior of the --version-revisions and --expected-status options that are described in the version revision and expected status sections. For example, the following command attempts to dispose a package version but fails due to a mismatched expected status.

aws codeartifact dispose-package-versions —domain my_domain --domain-owner 111122223333 
--repository my_repo --format npm --package chalk --versions 4.0.0 
--expected-status Unlisted

Sample output:

{
    "successfulVersions": {},
    "failedVersions": {
        "4.0.0": {
            "errorCode": "MISMATCHED_STATUS",
            "errorMessage": "current status: Published, expected status: Unlisted"
        }
    }
}

If the same command is run again with an --expected-status of Published, the disposal will succeed.

aws codeartifact dispose-package-versions —domain my_domain --domain-owner 111122223333 
--repository my_repo --format npm --package chalk --versions 4.0.0 
--expected-status Published

Sample output:

{
    "successfulVersions": {
        "4.0.0": {
            "revision": "E3lhBp0RObRTut4pkjV5c1AQGkgSA7Oxtil6hMMzelc=",
            "status": "Disposed"
        }
    },
    "failedVersions": {}
}