> 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/go-modules.md).

# Go modules

Go modules - host Go packages in Harness Artifacts

Use a **Go modules** registry to host private Go modules, resolved using the standard Go module proxy 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 Go 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.

{% hint style="info" %}
**Go installation**

Setup steps vary by operating system and package manager. To install Go for your platform, go to the [Go installation guide](https://go.dev/doc/install) for setup details.
{% endhint %}

## Create a Go registry

To create a Go 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 **Go** 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 Go modules from external sources when they are not available locally. The default upstream is `proxy.golang.org`.

### 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 **Go** as the **Registry type**.
7. Select the **Source**: **GoProxy** or **Custom**.
   * If you select **Custom**, specify the **Remote registry URL** (for example, `https://proxy.golang.org`).
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 Go proxies.
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 Go modules Artifact.
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 module is not found in your Harness registry, the upstream proxy fetches it from the remote registry, such as `proxy.golang.org`, and caches it.
{% endhint %}

## Go modules client setup

In your Go modules Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token, then setup instructions for configuring, publishing, and resolving Go modules.

### Generate an identity token

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

1. In your Go modules 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

In the code samples, replace the values in angle brackets with your own values.

**1. Configure GOPROXY**

Set `GOPROXY` to your Harness registry address:

```bash
export GOPROXY="https://<EMAIL>:<IDENTITY_TOKEN>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/go"
```

**2. Publish the module**

Run the following command from your project's root directory to publish your Go module to the registry:

```bash
hc artifact push go <REGISTRY_NAME> <MODULE_DIR> --pkg-url pkg.harness.io --version <VERSION>
```

**3. Use the module**

Install the module with the Go client:

```bash
go get <ARTIFACT_NAME>@<VERSION>
```

Then import the module in your project, and run:

```bash
go mod tidy
```

## Setup verification

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

1. In a new directory with no modules in the local Go module cache, use `go get` to resolve the module you published.
2. Confirm that the client downloaded the module from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the module 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 Go module 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: |
        hc artifact push go <REGISTRY_NAME> <MODULE_DIR> --pkg-url pkg.harness.io --version "$PACKAGE_VERSION"
```

## Troubleshooting

<details>

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

Check that the email address and identity token in your `GOPROXY` value match the ones shown in **Setup Client**. If the token expired or was revoked, generate a new one and update your `GOPROXY` value.

</details>

<details>

<summary>`hc artifact push go` returns `409 Conflict`</summary>

Module versions are immutable after publish. Tag a new SemVer version, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`go get` cannot find a module, or resolves the wrong version</summary>

Check that the module path and version tag match the values you used when you published the module, and that `GOPROXY` points at the correct account ID and registry name.

</details>

<details>

<summary>`go get` or `go build` still resolves an old version after a new publish</summary>

Clear the local module cache with `go clean -modcache`, then run `go get <ARTIFACT_NAME>@<VERSION>` again to pull the version you published.

</details>

<details>

<summary>A `go get` resolution is slow or times out</summary>

Confirm network egress to `pkg.harness.io` from your client, and confirm `GOPROXY` is set correctly in your shell or `go env`. A misconfigured `GOPROXY` falls back to the public Go proxy and can appear as a slow or failed resolution instead of a clear error.

</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 module to a virtual Go modules registry instead, or let the upstream proxy cache public modules 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 %}
