> 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/setup/dart.md).

# Dart

Dart - publish Dart packages to Harness Artifacts

Use a **Dart** registry to host private Dart and Flutter packages, resolved using the Dart pub protocol.

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry, and confirm that it works.

## Before you begin

* Install the Dart CLI (`dart`) or the Flutter CLI (`flutter`) on your local machine.
* Install the Harness CLI (`hc`). You use it to publish packages to your registry.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Dart registry

To create a Dart registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Dart** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Dart packages from external sources when they are not available locally. The default upstream is `pub.dev`.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Dart** as the **Registry type**.
7. Select the **Source**: **Pub.dev** or **Custom**.
   * If you select **Custom**, specify the **Remote registry URL** (for example, `https://pub.dev`).
8. Select the **Authentication method**.
   * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Anonymous**: No credentials required. This works for public Dart registries such as pub.dev.
9. Select **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing Dart registry.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Click **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Click **Apply**.
7. Select **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If a package is not found in your Harness registry, the upstream proxy fetches it from the remote registry, such as `pub.dev`, and caches it.
{% endhint %}

## Dart client setup

In your Dart Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token, then setup instructions for the Dart CLI or the Flutter CLI.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your Dart Artifact, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. You use it in the following steps in place of `<IDENTITY_TOKEN>`.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the client

Select **Dart CLI** or **Flutter CLI** for your client. In the code samples, replace the values in angle brackets with your own values.

{% tabs %}
{% tab title="Dart CLI" %}
**1. Add the authentication token**

Add the identity token to Dart pub:

```bash
dart pub token add https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/pub/
```

Enter your `<IDENTITY_TOKEN>` when prompted.

**2. Publish a package**

In your package's `pubspec.yaml`, set the registry URL:

```yaml
publish_to: https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/pub/
name: <ARTIFACT_NAME>
version: <VERSION>
description: <DESCRIPTION>
environment:
  sdk: ">=3.0.0 <4.0.0"
```

Then publish the package:

```bash
dart pub publish
```

**3. Install a package**

In your consuming project's `pubspec.yaml`, add the dependency pointing to the hosted URL:

```yaml
dependencies:
  <ARTIFACT_NAME>:
    hosted:
      name: <ARTIFACT_NAME>
      url: https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/pub/
    version: <VERSION>
```

Then fetch it:

```bash
dart pub get
```

{% endtab %}

{% tab title="Flutter CLI" %}
**1. Add the authentication token**

Add the identity token to Flutter pub:

```bash
flutter pub token add https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/pub/
```

Enter your `<IDENTITY_TOKEN>` when prompted.

**2. Publish a package**

In your package's `pubspec.yaml`, set the registry URL:

```yaml
publish_to: https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/pub/
name: <ARTIFACT_NAME>
version: <VERSION>
description: <DESCRIPTION>
environment:
  sdk: ">=3.0.0 <4.0.0"
```

Then publish the package:

```bash
flutter pub publish
```

**3. Install a package**

In your consuming Flutter project's `pubspec.yaml`, add the dependency pointing to the hosted URL:

```yaml
dependencies:
  <ARTIFACT_NAME>:
    hosted:
      name: <ARTIFACT_NAME>
      url: https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/pub/
    version: <VERSION>
```

Then fetch it:

```bash
flutter pub get
```

{% endtab %}
{% endtabs %}

## Setup verification

Confirm that your registry serves the package you published. To verify your setup:

1. In a new directory with no packages in the local pub cache, use `dart pub get` or `flutter pub get` to resolve the package you published.
2. Confirm that the client downloaded the package from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the package and version appear in the package list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step publishes a Dart package on every version tag. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        sed -i "s/^version: .*/version: $PACKAGE_VERSION/" pubspec.yaml
        dart pub publish --force
```

## Troubleshooting

<details>

<summary>`dart pub get` fails with `401 Unauthorized` or `403 Forbidden`</summary>

Check that the identity token in your `dart pub token add` configuration matches the one shown in **Setup Client**. If the token expired or was revoked, generate a new one, remove the old token with `dart pub token remove`, and add the new one.

</details>

<details>

<summary>`dart pub publish` fails because the version already exists</summary>

Package versions are immutable after publish. Bump the `version` field in `pubspec.yaml` to a new SemVer version, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`dart pub get` cannot find a package, or resolves the wrong version</summary>

Check that the package name and version in `pubspec.yaml` match the values you used when you published the package, and that the hosted `url` points at the correct account ID and registry name.

</details>

<details>

<summary>`dart pub get` or `flutter pub get` still resolves an old version after a new publish</summary>

Run `dart pub cache repair` or `flutter pub cache repair` to refresh the local pub cache, then fetch the dependency again.

</details>

<details>

<summary>Setup Client omits publish instructions for an upstream proxy registry</summary>

An upstream proxy registry is pull-only, so **Setup Client** does not show publish instructions for it. Publish your package to a virtual Dart registry instead, or let the upstream proxy cache public packages on first resolution.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
