> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/get-started/quickstart.md).

# Quickstart

Create a registry, generate an identity token, and push your first artifact to Harness Artifacts in under 15 minutes, with steps for every format.

By the end of this guide, you will have a working private registry and your first artifact stored safely inside it. Select your format (Docker is shown first) and follow the five steps in order. The whole thing takes under 15 minutes.

## Before you begin

Three things to have ready:

* A Harness account with the **Artifact Registries: Create/Edit** permission at the scope (account, organization, or project) where you want to work. Go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md) if you need help checking your permissions.
* The CLI for your format installed locally: Docker, Maven, npm, pip, NuGet, Helm, or curl.
* An [**identity token**](https://developer.harness.io/artifact-registry/3.0/concepts/authentication-and-identity-tokens.md). You generate one in Step 3, so there is no need to find one now.

{% hint style="info" %}
**FORMAT NOT IN THE LIST?**

Registry types roll out progressively. If the type you need is missing from the create form, contact [Harness Support](mailto:support@harness.io) to have it enabled on your account.
{% endhint %}

***

## Step 1: Open Artifact Registry

1. In the navigation menu, select **Artifacts**.

You land on the **Registries** view, your home base for creating and managing registries.

![Registries list showing existing registries with their visibility, type, size, artifact count, and the Create registry button](https://3872764042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6p7kagx6lOgVXV11Eevj%2Fuploads%2Fgit-blob-b884b2e0f0b6f4dc9e2a233bb2f7601ca77b4b76%2Fregistries-list-view.png?alt=media)

{% hint style="info" %}
**SCOPE**

Registries are scoped to the level where you create them: account, organization, or project. A registry created at the account level is visible across all organizations and projects under it. Check the scope selector before you continue.
{% endhint %}

***

## Step 2: Create a registry

A registry is the container that holds your artifacts. Give it a name, pick a type, and you are done in about 30 seconds.

![Create registry panel with fields for registry name, description, visibility, and registry type](https://3872764042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6p7kagx6lOgVXV11Eevj%2Fuploads%2Fgit-blob-e97d61f3bd582fdfa199057f273955187588773a%2Fcreate-registry-panel.png?alt=media)

*The panel is the same for every format. Only the Registry type selection changes to match the tab you follow below.*

{% tabs %}
{% tab title="Docker" %}

1. Select **+ Create Registry**.
2. Specify a **Registry name**. Names must start with a letter, can only contain lowercase alphanumerics, hyphens (`-`), underscores (`_`), and periods (`.`), and must be unique to your Harness account.
3. Optionally, add a **Description**.
4. Choose visibility between **Public** and **Private**. The default is *Private*.
5. Select **Docker** as the **Registry type**.
6. Select **Save**.
7. Select **Create** to finalize.

Your registry is ready. The URL for your client is:

```
pkg.harness.io/<account-id>/<registry-name>
```

{% endtab %}

{% tab title="Maven" %}

1. Select **+ Create Registry**.
2. Specify a **Registry name**. Names must start with a letter, can only contain lowercase alphanumerics, hyphens (`-`), underscores (`_`), and periods (`.`), and must be unique to your Harness account.
3. Optionally, add a **Description**.
4. Choose visibility between **Public** and **Private**. The default is *Private*.
5. Select **Maven** as the **Registry type**.
6. Select **Save**.
7. Select **Create** to finalize.

Your registry is ready. The URL for your client is:

```
https://pkg.harness.io/pkg/<account-id>/<registry-name>/maven
```

{% endtab %}

{% tab title="npm" %}

1. Select **+ Create Registry**.
2. Specify a **Registry name**. Names must start with a letter, can only contain lowercase alphanumerics, hyphens (`-`), underscores (`_`), and periods (`.`), and must be unique to your Harness account.
3. Optionally, add a **Description**.
4. Choose visibility between **Public** and **Private**. The default is *Private*.
5. Select **npm** as the **Registry type**.
6. Select **Save**.
7. Select **Create** to finalize.

Your registry is ready. The URL for your client is:

```
https://pkg.harness.io/pkg/<account-id>/<registry-name>/npm/
```

{% endtab %}

{% tab title="Python / PyPI" %}

1. Select **+ Create Registry**.
2. Specify a **Registry name**. Names must start with a letter, can only contain lowercase alphanumerics, hyphens (`-`), underscores (`_`), and periods (`.`), and must be unique to your Harness account.
3. Optionally, add a **Description**.
4. Choose visibility between **Public** and **Private**. The default is *Private*.
5. Select **Python** as the **Registry type**.
6. Select **Save**.
7. Select **Create** to finalize.

Your registry is ready. The URL for your client is:

```
https://pkg.harness.io/pkg/<account-id>/<registry-name>/python
```

{% endtab %}

{% tab title="NuGet" %}

1. Select **+ Create Registry**.
2. Specify a **Registry name**. Names must start with a letter, can only contain lowercase alphanumerics, hyphens (`-`), underscores (`_`), and periods (`.`), and must be unique to your Harness account.
3. Optionally, add a **Description**.
4. Choose visibility between **Public** and **Private**. The default is *Private*.
5. Select **NuGet** as the **Registry type**.
6. Select **Save**.
7. Select **Create** to finalize.

Your registry is ready. The URL for your client is:

```
https://pkg.harness.io/pkg/<account-id>/<registry-name>/nuget/index.json
```

{% endtab %}

{% tab title="Helm OCI" %}

1. Select **+ Create Registry**.
2. Specify a **Registry name**. Names must start with a letter, can only contain lowercase alphanumerics, hyphens (`-`), underscores (`_`), and periods (`.`), and must be unique to your Harness account.
3. Optionally, add a **Description**.
4. Choose visibility between **Public** and **Private**. The default is *Private*.
5. Select **Helm OCI** as the **Registry type**.
6. Select **Save**.
7. Select **Create** to finalize.

Your registry is ready. The URL for your client is:

```
pkg.harness.io/<account-id>/<registry-name>
```

{% endtab %}

{% tab title="Generic" %}

1. Select **+ Create Registry**.
2. Specify a **Registry name**. Names must start with a letter, can only contain lowercase alphanumerics, hyphens (`-`), underscores (`_`), and periods (`.`), and must be unique to your Harness account.
3. Optionally, add a **Description**.
4. Choose visibility between **Public** and **Private**. The default is *Private*.
5. Select **Generic** as the **Registry type**.
6. Select **Save**.
7. Select **Create** to finalize.

Your registry is ready. Files you upload are available under:

```
https://pkg.harness.io/pkg/<account-id>/<registry-name>/files/
```

{% endtab %}
{% endtabs %}

***

## Step 3: Generate an identity token

Your identity token is the password your tools use to authenticate with the registry. You generate it directly from the registry you just created:

1. Open your registry. Select **Setup Client**, which appears in the row menu on the Registries list and at the top of the registry detail page.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token now; it is shown only once.

![Client setup panel with the Generate Token button highlighted and the Expiration dropdown open, showing 30 Days, 90 Days, 180 Days, and Custom options](https://3872764042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6p7kagx6lOgVXV11Eevj%2Fuploads%2Fgit-blob-7a1bf8ac39441ce991ea08f6b6d7780691439b76%2Fdocker-client-setup-generate-token.png?alt=media)

*Shown here for Docker. The Setup Client panel for every other format follows the same Generate Token and Expiration flow.*

Store it somewhere safe, like a password manager or secrets vault, before closing the panel.

{% hint style="warning" %}
**TOKEN EXPIRY**

The identity token stops working after the expiration you select. For CI pipelines or service accounts that need longer-lived credentials, generate a token at the account or organization scope from **Account Settings > API Keys** and rotate it on a schedule.
{% endhint %}

***

## Step 4: Connect your client and push

Now point your local tools at the registry and push something. In the commands that follow, replace the placeholders with your real values: `<account-id>` and `<registry-name>` are both visible in the registry URL from Step 2, and `<identity-token>` is the token you just copied.

The core push action for each format:

* **Docker**: authenticate with `docker login` and run `docker push` against `pkg.harness.io/<account-id>/<registry-name>/<image-name>:<tag>`.
* **Maven**: add the registry to `pom.xml` and `settings.xml`, then run `mvn deploy`.
* **npm**: point `~/.npmrc` at the registry and run `npm publish`.
* **Python**: configure Twine in `~/.pypirc` and run `twine upload`.
* **NuGet**: add the registry as a package source and run `nuget push`.
* **Helm OCI**: authenticate with `helm registry login` and run `helm push`.
* **Generic**: `curl` a `PUT` request with the file to the registry's files endpoint.

Select the matching tab below for the full command sequence.

{% tabs %}
{% tab title="Docker" %}
**Log in to the registry**

```bash
docker login pkg.harness.io
```

At the prompts, enter your Harness account email as the **Username** and `<identity-token>` as the **Password**.

**Tag a local image for the registry**

```bash
docker tag <local-image>:<tag> \
  pkg.harness.io/<account-id>/<registry-name>/<image-name>:<tag>
```

**Push the image**

```bash
docker push pkg.harness.io/<account-id>/<registry-name>/<image-name>:<tag>
```

**Pull the image back down**

```bash
docker pull pkg.harness.io/<account-id>/<registry-name>/<image-name>:<tag>
```

{% endtab %}

{% tab title="Maven" %}
**Tell Maven where to publish: add this to `pom.xml`**

```xml
<distributionManagement>
  <repository>
    <id>harness</id>
    <url>https://pkg.harness.io/pkg/<account-id>/<registry-name>/maven</url>
  </repository>
  <snapshotRepository>
    <id>harness</id>
    <url>https://pkg.harness.io/pkg/<account-id>/<registry-name>/maven</url>
  </snapshotRepository>
</distributionManagement>
```

**Add your credentials: create or update `~/.m2/settings.xml`** (macOS/Linux) or `%USERPROFILE%\.m2\settings.xml` (Windows)

The `<id>` here must match the one you used in `pom.xml`.

```xml
<settings>
  <servers>
    <server>
      <id>harness</id>
      <username><your-harness-email></username>
      <password><identity-token></password>
    </server>
  </servers>
</settings>
```

**Push your artifact**

```bash
mvn deploy
```

**Pull a dependency**

Add a `<repositories>` block to `pom.xml` with the same `<id>` and URL, then resolve:

```xml
<repositories>
  <repository>
    <id>harness</id>
    <url>https://pkg.harness.io/pkg/<account-id>/<registry-name>/maven</url>
    <releases><enabled>true</enabled></releases>
    <snapshots><enabled>true</enabled></snapshots>
  </repository>
</repositories>
```

```bash
mvn dependency:resolve
```

{% endtab %}

{% tab title="npm" %}
**Point npm at your registry: create or update `~/.npmrc`**

```ini
registry=https://pkg.harness.io/pkg/<account-id>/<registry-name>/npm/
//pkg.harness.io/pkg/<account-id>/<registry-name>/npm/:_authToken=<identity-token>
```

**Publish a package**

```bash
npm publish
```

**Install a package from the registry**

```bash
npm install <package-name>@<version>
```

{% endtab %}

{% tab title="Python / PyPI" %}
**Configure Twine: create or update `~/.pypirc`**

```ini
[distutils]
index-servers = harness

[harness]
repository = https://pkg.harness.io/pkg/<account-id>/<registry-name>/python
username = <your-harness-email>
password = <identity-token>
```

**Build and publish your package**

```bash
python -m build
python -m twine upload --repository harness dist/*
```

**Install a package from the registry**

Encode `@` as `%40` in your email address in the URL (for example, `user@example.com` becomes `user%40example.com`).

```bash
pip install \
  --index-url https://user%40example.com:<identity-token>@pkg.harness.io/pkg/<account-id>/<registry-name>/python/simple \
  --no-deps \
  <package-name>==<version>
```

{% endtab %}

{% tab title="NuGet" %}
**Add the registry as a package source**

```bash
nuget sources add -Name harness -Source https://pkg.harness.io/pkg/<account-id>/<registry-name>/nuget/index.json -Username <your-harness-email> -Password <identity-token>
nuget setapikey <identity-token> -Source harness
```

**Push a package**

```bash
nuget push <package-file> -Source harness
```

**Install a package from the registry**

```bash
nuget install <package-name> -Version <version> -Source harness
```

{% endtab %}

{% tab title="Helm OCI" %}
**Log in to the registry**

```bash
helm registry login pkg.harness.io
```

At the prompts, enter your Harness account email as the **Username** and `<identity-token>` as the **Password**.

**Package and push a chart**

```bash
helm package ./my-chart
helm push my-chart-<version>.tgz \
  oci://pkg.harness.io/<account-id>/<registry-name>
```

**Pull a chart**

```bash
helm pull oci://pkg.harness.io/<account-id>/<registry-name>/my-chart \
  --version <version>
```

{% endtab %}

{% tab title="Generic" %}
**Publish a file**

```bash
curl -XPUT 'https://pkg.harness.io/pkg/<account-id>/<registry-name>/files/<artifact-name>/<version>/<file-path>' \
  --header 'x-api-key: <identity-token>' -T '<local-file-path>'
```

**Download the file**

```bash
curl --location 'https://pkg.harness.io/pkg/<account-id>/<registry-name>/files/<artifact-name>/<version>/<file-path>' \
  --header 'x-api-key: <identity-token>' -J -O
```

{% endtab %}
{% endtabs %}

***

## Step 5: Verify your artifact in the registry

Head back to Artifact Registry and confirm the push worked:

1. In the navigation menu, select **Artifacts**.
2. Find your artifact in the list. The row should show the artifact name and, for Docker images, the tag you pushed.
3. Select the artifact row to open the version detail page. Confirm the following to verify the push was successful:
   * The **digest** matches what your CLI reported after the push.
   * For Docker images: the **Artifact Details** tab shows the image layers.
   * For Maven: the **Artifact Details** tab lists the `.jar`, `.pom`, and checksum files.
   * For npm, PyPI, NuGet, Helm: the **Overview** tab shows the version and package metadata.
   * For Generic: the **Overview** tab shows the file name, size, and checksum.
4. The **Vulnerabilities** column on the Artifacts list updates automatically once the security scan completes; it may show **Not scanned** for a minute or two while the evaluation runs.

{% hint style="success" %}
**AUTOMATIC SECURITY SCANNING**

Configure a scanner on the registry to evaluate every artifact you push automatically. Artifacts that fail a blocking policy are quarantined and cannot be pulled until the issue is resolved. To enable Aqua Trivy or Grype, go to [Configure security scanning](https://developer.harness.io/artifact-registry/3.0/registries/configure-security-scanning.md).
{% endhint %}

***

## What to do next

Now that your registry is running, here are the most useful things to set up:

* **Scan for vulnerabilities**: Go to [Configure security scanning](https://developer.harness.io/artifact-registry/3.0/registries/configure-security-scanning.md) to enable Aqua Trivy or Grype. Every artifact you push is evaluated automatically, and anything that fails a policy gets quarantined before it can cause problems downstream.
* **Cache upstream packages**: Go to [Add and prioritize upstream proxies](https://developer.harness.io/artifact-registry/3.0/registries/add-and-prioritise-upstream-proxies.md) to pull and cache artifacts from Docker Hub, Maven Central, npm, PyPI, and other sources. Your builds stop hitting rate limits and keep working even when upstream registries are down.
* **Clean up old versions automatically**: Go to [Create a lifecycle rule](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/create-a-cleanup-rule.md) to set policies that delete artifact versions based on age, usage, or count. Storage stays tidy without manual intervention.

{% @harness-feedback/feedback %}
