> 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/r-cran.md).

# R(CRAN)

R (CRAN) - host R packages in Harness Artifacts

Use an **R (CRAN)** registry to host private R packages or cache public packages from CRAN-compatible repositories through an upstream proxy.

## What you will learn from this topic

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

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

## Before you begin

* Install R on your local machine, including the standard package tools (`install.packages`).
* Install `curl` on your local machine. You use it to upload packages to your registry.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a CRAN registry

To create a CRAN registry:

1. In Artifact Registry, select **Registries**.
2. Click **+ 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 **CRAN** 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 R packages from external CRAN-compatible repositories when they are not available locally. The default upstream is `https://cran.r-project.org`.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Click 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 **CRAN** as the **Registry type**.
7. Select the **Source**: **CRAN** or **Custom**.
   * If you select **Custom**, specify the **Remote registry URL** (for example, `https://cran.r-project.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 CRAN mirrors.
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 R (CRAN) 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. Select **Apply**.
7. Click **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 CRAN-compatible repository and caches it.
{% endhint %}

## R (CRAN) client setup

In your Harness R (CRAN) Artifact, select the required CRAN registry, and then select **Setup Client**. The dialog gives you an identity token, then setup instructions for configuring R, publishing packages, and installing packages.

### Generate an identity token

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

1. In your Harness R (CRAN) 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. Use the token in place of `<API_KEY>` in the following steps.

{% 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. **Setup Client** fills in your account ID and registry name.

**1. Configure R**

Point R at this registry as a CRAN-like repository.

Store your identity token in a `~/.netrc` file with mode `0600`. Use your Harness account email as the login, and the identity token as the password:

{% code overflow="wrap" %}

```bash
cat <<'NETRC' > ~/.netrc
machine pkg.harness.io
  login <HARNESS_EMAIL>
  password <API_KEY>
NETRC
chmod 600 ~/.netrc
```

{% endcode %}

Set the repository for the current R session. Downloads use the `curl` method with `-n` so `curl` reads credentials from `~/.netrc`:

{% code overflow="wrap" %}

```r
options(
  repos = c(
    HARNESS = "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/cran"
  ),
  download.file.method = "curl",
  download.file.extra = "-n -L -f"
)
```

{% endcode %}

Persist across sessions by appending the same line to `~/.Rprofile`:

{% code overflow="wrap" %}

```bash
echo 'options(repos = c(HARNESS = "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/cran"), download.file.method = "curl", download.file.extra = "-n -L -f")' >> ~/.Rprofile
```

{% endcode %}

**2. Install a package**

Install R packages from this registry:

```r
install.packages("<ARTIFACT_NAME>")
```

**3. Install an archived (older) version**

The live index only lists the latest version of a package. Superseded source versions are still downloadable from the `Archive/` path.

Install directly from the archived source tarball:

{% code overflow="wrap" %}

```r
install.packages(
  "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/cran/src/contrib/Archive/<ARTIFACT_NAME>/<ARTIFACT_NAME>_<VERSION>.tar.gz",
  repos = NULL,
  type = "source"
)
```

{% endcode %}

**4. Upload a package**

Upload an R source or binary archive to the registry using the CRAN repository layout.

Upload a source package to `src/contrib` (produced by `R CMD build`):

{% code overflow="wrap" %}

```bash
curl --location --request PUT \
  'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/src/contrib/<FILE_NAME>' \
  --header 'x-api-key: <API_KEY>' \
  --upload-file '<FILE_PATH>'
```

{% endcode %}

Upload a Windows binary to `bin/windows/contrib/<R_MINOR_VERSION>` (for example, `4.4`):

{% code overflow="wrap" %}

```bash
curl --location --request PUT \
  'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/bin/windows/contrib/<R_MINOR_VERSION>/<FILE_NAME>' \
  --header 'x-api-key: <API_KEY>' \
  --upload-file '<FILE_PATH>'
```

{% endcode %}

Upload a macOS binary to `bin/macosx/<FLAVOR>/contrib/<R_MINOR_VERSION>` (for example, `big-sur-arm64`, `4.4`):

{% code overflow="wrap" %}

```bash
curl --location --request PUT \
  'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/bin/macosx/<FLAVOR>/contrib/<R_MINOR_VERSION>/<FILE_NAME>' \
  --header 'x-api-key: <API_KEY>' \
  --upload-file '<FILE_PATH>'
```

{% endcode %}

## Setup verification

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

1. In a new R session, use `install.packages` to install the package you published.
2. Confirm that R downloaded the package from your Harness registry address, that 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 shows the shape of a publish step. Replace the placeholder values with your own. 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
      command: |
        curl --location --request PUT \
          "https://pkg.harness.io/pkg/${ACCOUNT_ID}/${REGISTRY_NAME}/files/src/contrib/${FILE_NAME}" \
          --header "x-api-key: ${API_KEY}" \
          --upload-file "${FILE_PATH}"
```

## Troubleshooting

<details>

<summary>`install.packages` fails with `401` or `403` against an R (CRAN) registry</summary>

Confirm `~/.netrc` lists `machine pkg.harness.io`, your Harness account email as `login`, and the identity token from **Setup Client** as `password`. The file must be mode `0600` (`chmod 600 ~/.netrc`). Confirm `download.file.method` is `curl` and `download.file.extra` is `-n -L -f` so `curl` reads that file. Regenerate the token if it expired, update `~/.netrc`, and verify your principal has Artifact Registry permissions on the registry.

For uploads, confirm the `curl` PUT includes `--header 'x-api-key: <API_KEY>'` with the same identity token.

</details>

<details>

<summary>Setup Client does not show Upload a package</summary>

Upload is available only on a virtual CRAN registry. An upstream CRAN registry is pull-only, so **Setup Client** omits **Upload a package**. Publish to a virtual registry instead, or cache packages through the upstream proxy.

</details>

<details>

<summary>Publish to a CRAN registry returns `409 Conflict`</summary>

Package versions are immutable after publish. Use a new package version, or delete the existing version only if your registry retention and lifecycle policies allow it. Do not PUT to an upstream registry.

</details>

<details>

<summary>`install.packages` returns `404 Not Found` or cannot find an older package version</summary>

Confirm the registry URL includes your account ID and registry name. The live index lists only the latest version, so install older versions from the `src/contrib/Archive` tarball URL. If you rely on an upstream proxy, confirm the proxy is attached and the remote CRAN URL is reachable.

</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 %}
