> 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/platform-integrations/harness-ci.md).

# Harness CI

Build, upload, and reference artifacts in Harness Artifacts directly from Harness CI pipelines without configuring external connectors.

Harness CI integrates natively with Harness Artifacts, so you can build, upload, and reference artifacts without configuring a Docker connector or managing external credentials. Harness Artifacts is the default registry type in CI steps, and the pipeline identity handles authentication automatically.

This page covers three built-in integration points: building and pushing Docker images, uploading artifacts of any supported package type, and referencing Harness Artifacts images in Run and Plugin steps.

***

## How it works

Harness CI provides native steps that connect to Harness Artifacts directly within the platform:

1. **Build and Push to Docker Registry**. Build a Docker image and push it to a registry in Harness Artifacts. The step selects Harness Artifacts as the default registry type, so no Docker connector is needed.
2. **Upload Artifacts to Harness Artifacts**. Upload build outputs of any supported package type (Maven, npm, Python, Go, Conda, Generic, and others) to a registry. This dedicated step uses the Harness CLI internally.
3. **Run and Plugin steps**. Reference container images stored in Harness Artifacts as the execution environment for Run and Plugin steps, without an external Docker connector.

In all three cases, the pipeline authenticates as the identity that runs it. That identity needs the appropriate access to the target registry.

***

## Before you begin

* **Harness account with Artifacts and CI enabled**. You need at least one registry created in Harness Artifacts. To create one, go to [Create a registry](https://developer.harness.io/artifact-registry/3.0/registries/create-a-registry.md).
* **Pipeline identity with registry access**. The identity that runs the pipeline needs write access (for build and upload steps) or read access (for Run and Plugin steps) to the target registry. To understand authentication, go to [Authentication and identity tokens](https://developer.harness.io/artifact-registry/3.0/concepts/authentication-and-identity-tokens.md).
* **A CI pipeline with a Build stage**. To learn about CI pipeline fundamentals, go to the [Harness CI documentation](https://developer.harness.io/continuous-integration).

***

## Build and push Docker images

The **Build and Push an image to Docker Registry** step connects to Harness Artifacts directly. You select a registry and image name from the Harness UI, with no Docker connector and no credentials file required.

1. **Open your Build stage**. In your CI pipeline, navigate to the **Build** stage where you want to add the push step.
2. **Add the Build and Push step**. Add a **Build and Push an image to Docker Registry** step. **Harness Artifacts** is the default registry type. Verify that it is selected.
3. **Select the registry**. In **Registry**, select the Harness Artifacts registry where you want to push the image. The dropdown lists all registries available in the current scope.
4. **Configure the image**. In **Image Name**, select an existing image or type the name of a new image you are building for the first time. In **Tags**, enter one or more image tags.
5. **Apply changes**. Select **Apply Changes**. The step is ready to run. No connector configuration is required.

<details>

<summary>Example YAML</summary>

```yaml
steps:
  - step:
      type: BuildAndPushDockerRegistry
      name: Build and Push to Artifacts
      identifier: build_and_push_ar
      spec:
        registryType: HarnessArtifactRegistry
        registry: my-docker-registry
        imageName: my-app
        tags:
          - latest
          - <+pipeline.sequenceId>
```

</details>

***

## Upload artifacts

The **Upload Artifacts to Harness Artifacts** step supports multiple package types and eliminates the need for external connectors or scripting. This step uses the Harness CLI internally to handle authentication and upload.

1. **Add the Upload Artifacts step**. In your Build stage, add an **Upload Artifacts to Harness Artifacts** step.
2. **Select the package type and registry**. Choose the package type that matches your artifact (for example, Maven, npm, Python, Go, Conda, or Generic). In **Registry**, select the target registry.
3. **Configure the source path**. In **Source Path**, enter the path to the artifact generated by a previous step. This path typically references build output, such as:

   * `/harness/target/*.jar` for Maven artifacts
   * `/harness/example.tar.gz` for npm tarballs
   * `/harness/build/` for Python wheels

   You can use Harness expressions to reference outputs from earlier steps (for example, `<+steps.build.output.outputVariables.ARTIFACT_PATH>`).
4. **Set additional fields if required**.
   * **Generic packages** require an explicit package name and version.
   * **Go packages** require an explicit version.

{% hint style="info" %}
The Upload Artifacts step is available in CI pipelines without enabling a feature flag. The pipeline identity needs write access to the target registry.
{% endhint %}

<details>

<summary>Example YAML: uploading a Conda package</summary>

```yaml
steps:
  - step:
      type: Run
      name: Download Conda Package
      identifier: download_conda_package
      spec:
        shell: Sh
        command: |-
          #!/bin/sh
          set -e
          PACKAGE_NAME="docutils-stubs"
          CHANNEL="conda-forge"
          JSON_DATA=$(curl -s "https://api.anaconda.org/package/${CHANNEL}/${PACKAGE_NAME}/files")
          LATEST_URL=$(echo "${JSON_DATA}" \
            | grep -o '"download_url": "[^"]*"' \
            | head -n 1 \
            | cut -d'"' -f4)
          case "${LATEST_URL}" in
            //* ) LATEST_URL="https:${LATEST_URL}" ;;
          esac
          FILE_NAME=$(basename "${LATEST_URL}")
          curl -L "${LATEST_URL}" -o "${FILE_NAME}"
          FILE_PATH="$(pwd)/${FILE_NAME}"
          echo "FILE_PATH=${FILE_PATH}" >> "${DRONE_OUTPUT}"
        outputVariables:
          - name: FILE_PATH
  - step:
      type: HarUpload
      name: Upload to Artifact Registry
      identifier: upload_to_registry
      spec:
        registryRef: my_conda_registry
        packageType: CONDA
        sourcePath: <+steps.download_conda_package.output.outputVariables.FILE_PATH>
```

In this example:

* **Step 1 (Run)** downloads a Conda package from conda-forge and outputs the file path using `DRONE_OUTPUT`.
* **Step 2 (HarUpload)** references the output variable from Step 1 and uploads the package to the specified registry.

</details>

***

## Referencing Harness Artifacts images in Run and Plugin steps

You can use container images stored in Harness Artifacts as the execution environment for CI **Run** and **Plugin** steps. This is useful when your build steps need a specific runtime image hosted in your private registry.

1. **Add a Run or Plugin step**. In your Build stage, add a **Run** step or **Plugin** step.
2. **Select the registry type**. **Harness Artifacts** is the default registry type. Verify that it is selected.
3. **Select the registry and image**. In **Registry**, select the Harness Artifacts registry that hosts the image. In the image field, enter the image name and version (for example, `my-build-tools:1.4.0`).
4. **Configure the step command**. Add the command your step needs to run, then select **Apply Changes**.

Run the pipeline to verify the step pulls the image from Harness Artifacts and executes successfully.

***

## Troubleshooting

<details>

<summary>The Build and Push step fails with a permissions error</summary>

The pipeline identity does not have write access to the target registry. Verify that the identity running the pipeline has the required RBAC permissions for the registry. To configure permissions, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).

</details>

<details>

<summary>The Upload Artifacts step does not find the source file</summary>

The source path may not match the output location from the previous step. Verify that the file exists at the specified path by adding an `ls -la` command in a Run step before the upload. If the file is generated dynamically, use a Harness output variable expression to reference the path.

</details>

<details>

<summary>A Run step cannot pull the image from Harness Artifacts</summary>

Verify that the pipeline identity has read access to the registry and that the image name and tag are correct. If the image was recently pushed, confirm it exists by checking the registry in the Harness UI.

</details>

***

## Next steps

* To push artifacts from external CI tools, go to [GitHub Actions and Harness Artifacts](https://developer.harness.io/artifact-registry/3.0/platform-integrations/github-actions.md) or [Jenkins and Harness Artifacts](https://developer.harness.io/artifact-registry/3.0/platform-integrations/jenkins.md).
* To deploy artifacts from Harness Artifacts in CD pipelines, go to [Harness CD and Harness Artifacts](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-cd.md).
* To configure client-side authentication for specific package types, go to the relevant page under [Setup](https://developer.harness.io/artifact-registry/3.0/setup/docker.md).
* To manage registries and artifacts from the CLI, go to [CLI reference](https://developer.harness.io/artifact-registry/3.0/reference/cli.md).

{% @harness-feedback/feedback %}
