Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ArtifactsRegistry TypesCi Cd

Dart

Create a Dart registry, generate an identity token, then publish and install Dart or Flutter packages using the Dart pub protocol.

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 quickstart guide, you will be able 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, perform the following steps:

  1. In Artifact Registry, select Registries.

  2. Select + Create Registry.

  3. Specify the Registry name.

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.

  1. Optionally, add a Description.

  2. Choose visibility between Public and Private. The default is Private.

  3. Select Dart as the Registry type.

  4. Click Save.

  5. 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, perform the following steps:

  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, perform the following steps:

  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.

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.

Dart client setup

In your Dart Artifact, select the registry, then select Set Up 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 Set Up 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>.

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.

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.

1. Add the authentication token

Add the identity token to Dart pub:

Enter your <IDENTITY_TOKEN> when prompted.

2. Publish a package

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

Then publish the package:

3. Install a package

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

Then fetch it:

1. Add the authentication token

Add the identity token to Flutter pub:

Enter your <IDENTITY_TOKEN> when prompted.

2. Publish a package

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

Then publish the package:

3. Install a package

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

Then fetch it:

Setup verification

Confirm that your registry serves the package you published. To verify your setup, perform the following steps:

  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 Set Up 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 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.

Troubleshooting

`dart pub get` fails with `401 Unauthorized` or `403 Forbidden`

Check that the identity token in your dart pub token add configuration matches the one shown in Set Up 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.

`dart pub publish` fails because the version already exists

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.

`dart pub get` cannot find a package, or resolves the wrong version

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.

`dart pub get` or `flutter pub get` still resolves an old version after a new publish

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

Set Up Client omits publish instructions for an upstream proxy registry

An upstream proxy registry is pull-only, so Set Up 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.

Next steps

Last updated

Was this helpful?