---
url: /en/artifact/intro.md
description: >
  Overview of the CNB Artifact Registry covering supported artifact types
  (Docker, Helm, Maven, npm, PyPI, etc.), how to manage registries, permission
  control, storage billing, and artifact migration.
---
This article introduces the basic concepts of the CNB Artifact Registry, including supported artifact types, management, permission control, storage billing, and artifact migration.

## Artifact Types

CNB currently supports the following artifact types:

| Artifact Type | Domain                           |
| :------------ | :------------------------------- |
| Docker        | \_\_ENV\_\_CNB\_DOCKER\_REGISTRY       |
| Docker Model  | \_\_ENV\_\_CNB\_DOCKER\_MODEL\_REGISTRY |
| Helm          | \_\_ENV\_\_CNB\_HELM\_REGISTRY         |
| Maven         | maven.\_\_ENV\_\_CNB\_HOST            |
| npm           | npm.\_\_ENV\_\_CNB\_HOST              |
| ohpm          | ohpm.\_\_ENV\_\_CNB\_HOST             |
| Nuget         | nuget.\_\_ENV\_\_CNB\_HOST            |
| Composer      | composer.\_\_ENV\_\_CNB\_HOST         |
| PyPI          | pypi.\_\_ENV\_\_CNB\_HOST             |
| Cargo         | cargo.\_\_ENV\_\_CNB\_HOST            |
| Conan         | conan.\_\_ENV\_\_CNB\_HOST            |

| Artifact Type | Domain                           |
| :------------ | :------------------------------- |
| Docker        | \_\_ENV\_\_CNB\_DOCKER\_REGISTRY       |
| Docker Model  | \_\_ENV\_\_CNB\_DOCKER\_MODEL\_REGISTRY |
| Helm          | \_\_ENV\_\_CNB\_HELM\_REGISTRY         |
| Maven         | maven.\_\_ENV\_\_CNB\_HOST            |
| npm           | npm.\_\_ENV\_\_CNB\_HOST              |
| ohpm          | ohpm.\_\_ENV\_\_CNB\_HOST             |
| Nuget         | nuget.\_\_ENV\_\_CNB\_HOST            |
| Composer      | composer.\_\_ENV\_\_CNB\_HOST         |
| PyPI          | pypi.\_\_ENV\_\_CNB\_HOST             |
| Cargo         | cargo.\_\_ENV\_\_CNB\_HOST            |
| Conan         | conan.\_\_ENV\_\_CNB\_HOST            |
| Generic       | generic.\_\_ENV\_\_CNB\_HOST          |

## Managing the Artifact Registry

The hierarchical relationship between artifact types, `group`, and `repository` in the UI is as follows:

```shell
test-org  # group
├── maven
├── npm
├── ohpm
├── nuget
├── composer
├── pypi
├── cargo
├── conan
└── test-git-repo # repository
    ├── docker
    ├── helm
    └── docker model
```

```shell
test-org  # group
├── maven
├── npm
├── ohpm
├── nuget
├── composer
├── pypi
├── cargo
├── conan
├── generic
└── test-git-repo # repository
    ├── docker
    ├── helm
    └── docker model
```

As shown above, Composer/Maven and other artifact types belong to a group, while Docker/Helm/Docker Model artifacts belong to a repository under the group. Their usage methods differ accordingly.

## Artifact Type Admission Restrictions

The Docker, Helm, and Docker Model registries are isolated from each other. **Each registry only accepts pushes of its own artifact type**. Pushing artifacts of other types will be rejected with an error.

| Registry | Allowed Artifacts |
|:---|:---|
| Docker | Container images (single/multi-arch), buildx registry cache, buildx attestations (provenance/SBOM attestations) |
| Helm | Helm Charts (OCI format) |
| Docker Model | Docker Model artifacts |

See [Appendix: Supported Manifest Types for OCI Registries](./supported-manifest-types.md) for the manifest config mediaType of each type.

For example, pushing a Helm Chart to the Docker registry address, or pushing a container image to the Helm registry address, will be rejected:

```text
denied: artifact type "CHART" is not allowed to be pushed to a "docker" registry
```

Blobs already uploaded by a rejected push are not referenced by any artifact and will be automatically cleaned up by garbage collection (GC). No manual intervention is required.

### Using Docker/Helm/Docker Model Artifacts

Docker/Helm/Docker Model artifacts belong to a repository, so no manual creation is required. Log in, go to a repository's "Packages" page to view them.

### Using Composer/Maven Artifacts

#### Creating an Artifact Registry

Click the "+" button in the upper right corner to create a new artifact registry, or select "Your registries" from your avatar to use an existing one. Click "Usage Guidelines" after entering the registry.

### Deleting Artifacts

Enter the artifact registry, click the artifact name to enter it, and delete the entire artifact or a specific version.

### Deleting an Artifact Registry

Docker/Helm/Docker Model artifacts do not require manual deletion. Other artifact types can be deleted in "Registry Setting".

### Obtaining the Artifact Registry Address

View the artifact registry address in "Registry Setting" > "General".

## Permission Control

### Roles

The visibility of Docker/Helm/Docker Model artifacts is consistent with the visibility of the `repository` they belong to.
User access permissions for artifacts are determined by their `role` in the `repository`.

For Composer/Maven and other artifact types, visibility depends on the artifact registry's visibility. User access permissions for artifacts are determined by their `role` in the artifact registry.

A user's `role` in a `repository` can be viewed in "Repository" > "Settings" > "Members":
![](/images/artifact/en-git-repo-role.png)

A user's `role` in an artifact registry can be viewed in "Artifact Registry" > "Registry Setting" > "Members Manage":
![](/images/artifact/en-artifact-repo-role.png)

The table below lists the correspondence between artifact behaviors and required `roles`:

| Resource                            | Behavior | Required Role                           |
| :---------------------------------- | :------- | :-------------------------------------- |
| Public Artifact Registry Artifacts  | Pull     | Anyone can pull without authentication  |
| Public Artifact Registry Artifacts  | Push     | Developer or above                      |
| Public Artifact Registry Artifacts  | Delete   | Administrator or above                  |
| Private Artifact Registry Artifacts | Pull     | Guest or above, requires authentication |
| Private Artifact Registry Artifacts | Push     | Developer or above                      |
| Private Artifact Registry Artifacts | Delete   | Administrator or above                  |

### Access Tokens

When using command-line tools to read or write artifacts, whether an operation is authorized depends on the user's `role` and the permissions of the `access token` in the request.

If an `access token` is missing, the system treats it as anonymous access, which limits operation permissions.

The detailed authentication policy for the artifact registry is as follows:

1. Login: If the `access token` is valid, login is allowed; otherwise, it is denied.

2. Anonymous operations: Only pulling from public artifact registries is allowed; all other operations are denied.

3. Query, pull, and push operations: If the user's `role` has the required permissions and the `access token`'s `registry-package` scope includes the operation, it is allowed; otherwise, denied. Deletion operations follow the same rules.

4. If the `access token` specifies a scope (e.g., a specific repository or artifact registry) and the scope matches the accessed resource, the actual authorization scope is returned. Otherwise, the visibility of the resource is checked:
   * If the resource is public, pull operations are still allowed, but other operations are denied.
   * If the resource is private, all operations are denied.

5. If the user, token, or accessed resource is in an abnormal state (e.g., frozen), all operations are denied.
   Carrying an incorrect `access token` (e.g., expired after login, treated as an abnormal token) will also deny pulling from a public artifact registry.

The above policy is illustrated below (using pull operations as an example, where "token" refers to the CNB `access token` and "scope" refers to the `access token`'s authorization scope):

```mermaid
%%{init: {"themeVariables": {"fontSize": "10px"}, "themeConfig": {"nodeTextMargin": 2, "spacingFactor": 0.8}}}%%
flowchart LR
    A[User Pulls Artifact] --> B{Is Token Provided?}
    B -->|No| D{Is Artifact Public?}
    B -->|Yes| C{Does User Have Read Permission in Repository?}

    D -->|Yes| M[Pull Success]
    D -->|No| E[Pull Failed]
    
    C -->|No| E[Pull Failed]
    C -->|Yes| F{Is Token Valid and Active?}

    F -->|No| E
    F -->|Yes| H{Does Token Scope Include Read Permission for Artifact?}
    
    H -->|No| E
    H -->|Yes| I{Does Token Specify a Scope?}
    
    I -->|No| G[Pull Success]
    I -->|Yes| J{Does Scope Cover Target Repository?}

    J --> |No| N[Pull Failed]
    J --> |Yes| G
```

#### Creating an Access Token

Click "Avatar" > "Settings" > "Access tokens" > ["Add Access Token"](https://cnb.build/profile/token) to create a new `access token`.

![](/images/artifact/en-create-token.png)

For `access token` permissions, only the "Authorization Scope" registry section needs attention.

When selecting "Common Scenarios" as "Artifact Registry," only `registry-package` read/write permissions are granted by default.

If you need to delete artifacts via command-line tools (e.g., `npm unpublish`), you must also check `registry-package-delete` read/write permissions.

Additionally, "Specify Artifact Registry" in "Usage Scope" cannot select Docker, Helm, and Docker Model artifacts. Instead, select "Specify Repository" and then set "Common Scenarios" to "Artifact Registry."

#### Using Tokens in Workspaces and Cloud Native Build

There are three ways to use tokens:

1. Directly use environment variables `${CNB_TOKEN_USER_NAME}` `${CNB_TOKEN}` (recommended)
2. Manually create an `access token` and use it directly (not recommended)
3. Manually create an `access token`, write it to the [Secret Registry](../repo/secret.md#creating-a-keystore), and then [import it as an environment variable](../repo/secret.md#importing-as-environment-variables) (neutral)

**About Method 1:**

CNB provides built-in `access tokens` for Workspaces and Cloud Native Build (CI pipelines). If no special requirements exist, you can directly use these environment variables without manually creating additional `access tokens`. For details about the permissions of this `access token`, refer to [CNB\_TOKEN](../build/build-in-env.md#cnb_token).

## Capacity Statistics

Billing is based on the storage space occupied by artifacts hosted on CNB.
You can view the capacity of each artifact in the "Usage" section.

> **Note**: For Docker/Docker Model artifacts, duplicate base images are deduplicated before calculating capacity.

## Artifact Migration

To batch migrate artifacts from other registries to CNB, use the [CNB Artifact Migration Tool](https://cnb.cool/cnb/plugins/cnbcool/artifact-migrate).