> 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/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/harness-ci.md).

# Harness CI images

When you run a Harness CI build, the pipeline pulls the Harness CI images it needs from Docker Hub.

When a Harness CI pipeline runs, an *initialize* step runs automatically before other stage steps. It prepares the environment for your steps.

The *initialize* step prepares build infrastructure and pulls required Harness images. It uses Docker Hub by default. You can also use the [Harness project on GAR](http://us-docker.pkg.dev/gar-prod-setup/harness-public) or the [Harness ECR public gallery](https://gallery.ecr.aws/harness). Go to [Connect to the Harness container registry](https://developer.harness.io/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/connect-to-harness-container-image-registry-using-docker-connector.md) to configure your account and pipeline registry settings.

### What you will learn from this topic

By the end of this topic, you will be able to:

* Find the [Harness CI images](#harness-ci-images-list) and plugin images available on each supported registry.
* Understand how [Harness CI image pulls](#harness-ci-image-pulls) work, including anonymous access and Docker Hub rate limiting.
* Review how [Harness CI images are updated](#harness-ci-image-updates).
* [Specify the Harness CI images](#specify-the-harness-ci-images-used-in-your-pipelines) used in your pipelines with the `execution-config` API.
* Use the [Windows rootless](#windows-rootless) images.

### Harness CI images list <a href="#harness-ci-images-list" id="harness-ci-images-list"></a>

You can find Harness CI images on Docker Hub, the [Harness project on GAR](http://us-docker.pkg.dev/gar-prod-setup/harness-public), the [Harness ECR public gallery](https://gallery.ecr.aws/harness), or the Harness EU-GAR registry.

The following Harness CI images are available on Docker Hub, GAR, ECR, and EU-GAR. Build image tags change often.

* `harness/ci-addon`: Used to execute steps on containers in Kubernetes pods.
* `harness/ci-lite-engine`: Used to orchestrate execution of steps on Kubernetes pods.
* `harness/drone-git`: Used to clone git repos.
* `harness/harness-cache-server`: Used to cache dependencies and build artifacts.

Harness CI uses [Drone plugin images](https://console.cloud.google.com/gcr/images/gcr-prod/global/plugins) to run some operations. The following plugin images are available across all supported registries:

* `plugins/kaniko`: Used to build Docker images with kaniko and push to Docker registry for Kubernetes cluster build infrastructures.
* `plugins/kaniko-ecr`: Used to build Docker images with kaniko and push to AWS ECR for Kubernetes cluster build infrastructures.
* `plugins/kaniko-acr`: Used to build Docker images with kaniko and push to Azure ACR for Kubernetes cluster build infrastructures.
* `plugins/kaniko-gar`: Used to build Docker images with kaniko and push to Google Artifact Registry for Kubernetes cluster build infrastructures.
* `plugins/docker`: Used to build and push Docker images for Harness Cloud build infrastructures.
* `plugins/ecr`: Used to build and push Docker images to AWS ECR for Harness Cloud build infrastructures.
* `plugins/acr`: Used to build and push Docker images to Azure ACR for Harness Cloud build infrastructures.
* `plugins/gar`: Used to build and push Docker images to Google Artifact Registry for Harness Cloud build infrastructures.
* `plugins/buildx`: Used to build and push Docker images with Buildx.
* `plugins/buildx-ecr`: Used to build and push Docker images to AWS ECR with Buildx.
* `plugins/buildx-acr`: Used to build and push Docker images to Azure ACR with Buildx.
* `plugins/buildx-gar`: Used to build and push Docker images to Google Artifact Registry with Buildx.
* `plugins/cache`: Used to cache files to/from S3/GCS that help to expedite builds.
* `plugins/s3`: Used to upload files to AWS S3 buckets.
* `plugins/gcs`: Used to upload files to GCP GCS service.
* `plugins/artifactory`: Used to upload artifacts to JFrog Artifactory.
* `plugins/download-artifactory`: Used to download artifacts from JFrog Artifactory.
* `plugins/test-analysis`: Used for test intelligence and test report parsing.
* `plugins/artifact-metadata-publisher`: Used to publish artifact metadata.
* `plugins/aws-oidc`: Used for AWS OIDC-based authentication.
* `plugins/gcp-oidc`: Used for GCP OIDC-based authentication.
* `plugins/buildah-docker`: Used to build Docker images with Buildah.
* `plugins/drone-liquibase`: Used for database DevOps with Liquibase.
* `plugins/image-migration`: Used to migrate Docker images between registries.
* `plugins/email`: Used to send email notifications.
* `plugins/githubaction`: Used to run GitHub Actions in Harness CI.

If an image you need is not listed here or is unavailable on your expected registry, contact [Harness Support](https://support.harness.io/).

### Harness CI image pulls <a href="#harness-ci-image-pulls" id="harness-ci-image-pulls"></a>

By default, when a CI pipeline runs, the Harness Delegate uses a [Docker connector](broken://spaces/3F2TpHXhur2QtQnORSM9/pages/LZPXMHJjbQyZXdwC5Omo) to make an anonymous outbound connection to pull the Harness CI images from the public container registry where they are stored.

#### Do not pull images anonymously <a href="#i-dont-want-to-pull-images-anonymously" id="i-dont-want-to-pull-images-anonymously"></a>

If you do not want the Harness Delegate to pull images anonymously, you can use credentialed access instead. Go to [Connect to the Harness container image registry](https://developer.harness.io/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/connect-to-harness-container-image-registry-using-docker-connector.md) to configure credentialed access.

#### Do not pull images from a public registry <a href="#i-dont-want-to-pull-images-from-a-public-registry" id="i-dont-want-to-pull-images-from-a-public-registry"></a>

Harness CI images are stored in a public container registry. If you do not want to pull the images directly from the public registry, you can pull Harness images from your own private registry. Go to [Connect to the Harness container image registry](https://developer.harness.io/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/connect-to-harness-container-image-registry-using-docker-connector.md) to configure a private registry.

#### Docker Hub rate limiting <a href="#docker-hub-rate-limiting" id="docker-hub-rate-limiting"></a>

By default, Harness uses anonymous Docker access to [pull Harness images](https://developer.harness.io/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/harness-ci.md). If you experience rate limiting issues when pulling images, try one of these solutions:

* Use credentialed access, rather than anonymous access, to pull Harness CI images.
* Configure the default Docker connector to pull images from GAR or ECR instead of Docker Hub.
* Pull Harness images from your own private registry.

Go to [Connect to the Harness container image registry](https://developer.harness.io/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/connect-to-harness-container-image-registry-using-docker-connector.md) to configure these options.

{% hint style="info" %}
**Supported registry images**

Only the images listed in the [Harness CI images list](#harness-ci-images-list) are supported across Docker Hub, GAR, ECR, and EU-GAR. If an image you need is unavailable on your expected registry, contact [Harness Support](https://support.harness.io/).
{% endhint %}

{% hint style="warning" %}
**Public ECR does not avoid rate limiting on Harness Cloud**

Public ECR anonymous access is not a rate-limit-free alternative to Docker Hub if you use [Harness Cloud build infrastructure](https://developer.harness.io/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md). AWS ECR Public enforces a fixed anonymous pull limit per source IP. Harness Cloud runners run on GCP, so they get no AWS-side preferential treatment and hit the same limit as any other anonymous caller. GAR is the only anonymous option that avoids this cap on Harness Cloud.
{% endhint %}

### Harness CI image updates <a href="#harness-ci-image-updates" id="harness-ci-image-updates"></a>

Every week, based on changes, CI images are updated and listed on the [CI release notes](https://developer.harness.io/release-notes/software-delivery-agent/continuous-integration.md) page. We recommend maintaining a one-month window to run security scans or other tests on new CI build images before deploying them.

Harness updates `harness/ci-*` images, such as `harness/ci-addon` and `harness/ci-lite-engine`, according to the following release process:

* Harness publishes updates for all CI images weekly based on changes.
* Version numbers follow the x.y.z format, where x represents the major release number, y represents the minor release number, and z represents a hotfix or patch release number.
* You can choose to deploy the latest containers immediately upon release or download and scan them before deployment.
* If issues are found, patches will be applied to the latest version.

[Harness plugin images](https://console.cloud.google.com/gcr/images/gcr-prod/global/plugins) for SMP are updated as needed. All Harness image updates are backward-compatible. When you first deploy CI, Harness scans all `plugin` images you plan to use and addresses any vulnerabilities. After your initial deployment, Harness publishes updates to address new vulnerabilities based on our Service Level Agreement with your organization.

### Specify the Harness CI images used in your pipelines <a href="#specify-the-harness-ci-images-used-in-your-pipelines" id="specify-the-harness-ci-images-used-in-your-pipelines"></a>

You can use the Harness CI `execution-config` API to specify or update the Harness CI images used in your infrastructure by specifying image tags.

API key authentication is required. Go to [Manage API keys](https://developer.harness.io/harness-platform/use-harness-platform/automation/api/add-and-manage-api-keys.md) to create an API key. Go to the [Harness API documentation](https://apidocs.harness.io/#section/Introduction/Authentication) to configure authentication.

1. Send a `get-default-config` request to get a list of the latest Harness CI build images and tags. You can use the `infra` parameter to get `k8` images or `VM` images.

   ```json
   curl --location --request GET "https://app.harness.io/gateway/ci/execution-config/get-default-config?accountIdentifier=$YOUR_HARNESS_ACCOUNT_ID&infra=K8" \
   --header "X-API-KEY: $API_KEY"
   ```

   The response payload shows the latest supported images and their tags, for example:

   ```json
   {
     "status": "SUCCESS",
     "data": {
       "addonTag": "harness/ci-addon:1.16.92",
       "liteEngineTag": "harness/ci-lite-engine:1.16.92",
       "addonTagRootless": "harness/ci-addon:rootless-1.16.92",
       "liteEngineTagRootless": "harness/ci-lite-engine:rootless-1.16.92",
       "gitCloneTag": "harness/drone-git:1.6.9-rootless",
       "buildAndPushDockerRegistryTag": "plugins/kaniko:1.10.6",
       "buildAndPushECRTag": "plugins/kaniko-ecr:1.11.0",
       "buildAndPushACRTag": "plugins/kaniko-acr:1.11.2",
       "buildAndPushGCRTag": "plugins/kaniko-gcr:1.10.1",
       "buildAndPushGARTag": "plugins/kaniko-gar:1.11.1",
       "buildAndPushBuildxDockerRegistryTag": "plugins/buildx:1.3.3",
       "buildAndPushBuildxECRTag": "plugins/buildx-ecr:1.3.1",
       "buildAndPushBuildxGARTag": "plugins/buildx-gar:1.3.1",
       "buildAndPushBuildxACRTag": "plugins/buildx-acr:1.3.1",
       "gcsUploadTag": "plugins/gcs:1.6.3",
       "s3UploadTag": "plugins/s3:1.5.3",
       "artifactoryUploadTag": "plugins/artifactory:1.7.6",
       "cacheGCSTag": "plugins/cache:1.9.8",
       "cacheS3Tag": "plugins/cache:1.9.8",
       "cacheProxyImage": "harness/harness-cache-server:1.7.4",
       "securityTag": "harness/sto-plugin:latest",
       "sscaOrchestrationTag": "harness/ssca-plugin:0.39.0",
       "sscaEnforcementTag": "harness/ssca-plugin:0.39.0",
       "sscaArtifactSigningTag": "harness/ssca-artifact-signing-plugin:0.39.0",
       "sscaArtifactVerificationTag": "harness/ssca-artifact-signing-plugin:0.39.0",
       "sscaCdxgenOrchestrationTag": "harness/ssca-cdxgen-plugin:0.39.0",
       "provenanceTag": "harness/slsa-plugin:0.39.0",
       "slsaVerificationTag": "harness/slsa-plugin:0.39.0",
       "sscaComplianceTag": "harness/ssca-compliance-plugin:0.39.0",
       "iacmTerraform": "plugins/harness_terraform:dev",
       "iacmTerragrunt": "plugins/harness_terraform:dev",
       "iacmAnsible": "plugins/harness_terraform:dev",
       "iacmOpenTofu": "plugins/harness_terraform:dev",
       "iacmCheckov": "plugins/harness_checkov:dev",
       "iacmTFCompliance": "plugins/harness_tf_compliance:dev",
       "iacmTFLint": "plugins/harness_tf_lint:dev",
       "iacmTFSec": "plugins/harness_tf_sec:dev",
       "iacmModuleTest": "plugins/harness_terraform:dev",
       "cookieCutter": "harness/cookiecutter:latest",
       "createRepo": "harness/createrepo:latest",
       "directPush": "harness/directpush:latest",
       "registerCatalog": "harness/registercatalog:latest",
       "createCatalog": "harness/createcatalog:latest",
       "slackNotify": "harness/slacknotify:latest",
       "createOrganisation": "harness/createorganisation:latest",
       "createProject": "harness/createproject:latest",
       "createResource": "harness/createresource:latest",
       "updateCatalogProperty": "harness/updatecatalogproperty:latest"
     },
     "metaData": null,
     "correlationId": "08919155-a6d6-4bd3-8401-6b86318c85ca"
   }
   ```
2. Send a `get-customer-config` request to get the build images that your CI pipelines currently use. When `overridesOnly` is `true`, which is the default value, this endpoint returns the non-default images that your pipeline uses.

   ```json
   curl --location --request GET "https://app.harness.io/gateway/ci/execution-config/get-customer-config?accountIdentifier=$YOUR_HARNESS_ACCOUNT_ID&infra=K8&overridesOnly=true" \
   --header "X-API-KEY: $API_KEY"
   ```

   If the response contains `null`, your pipeline is using all default images, for example:

   ```json
   {
     "status": "SUCCESS",
     "data": {},
     "metaData": null,
     "correlationId": "11ce1bc8-b337-4687-9ab9-e13d553ae82f"
   }
   ```
3. Send an `update-config` (POST) request with a list of the images you want to update and the new tags to apply.

   ```json
   curl --location --request POST "https://app.harness.io/gateway/ci/execution-config/update-config?accountIdentifier=$YOUR_HARNESS_ACCOUNT_ID&infra=K8" \
   --header "X-API-KEY: $API_KEY" \
   --header 'Content-Type: application/json' \
   --data-raw '[
       {
           "field": "gitCloneTag",
           "value": "harness/drone-git:1.6.9-rootless"
       },
       {
           "field": "gcsUploadTag",
           "value": "plugins/gcs:1.6.3"
       }
   ]'
   ```
4. Send a `reset-config` (POST) request with a list of images to reset one or more images to their defaults.

   ```json
   curl --location --request POST "https://app.harness.io/gateway/ci/execution-config/reset-config?accountIdentifier=$YOUR_HARNESS_ACCOUNT_ID&infra=K8" \
   --header "X-API-KEY: $API_KEY" \
   --header 'Content-Type: application/json' \
   --data-raw '[
       {
           "field": "gitCloneTag"
       },
       {
           "field": "gcsUploadTag"
       }
   ]'
   ```

### Deprecation notice: app.harness Docker registry <a href="#deprecation-notice-appharness-docker-registry" id="deprecation-notice-appharness-docker-registry"></a>

Harness images are available on Docker Hub, the [Harness project on GAR](http://us-docker.pkg.dev/gar-prod-setup/harness-public), and the [Harness ECR public gallery](https://gallery.ecr.aws/harness). In a continuation of this effort, and to improve stability when pulling Harness-required images, Harness deprecated the Harness-hosted `app.harness` Docker registry effective 15 February 2024. Go to [Connect to the Harness container image registry](https://developer.harness.io/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/connect-to-harness-container-image-registry-using-docker-connector.md#deprecation-notice-appharness-docker-registry) to review the deprecation details.

### Windows rootless <a href="#windows-rootless" id="windows-rootless"></a>

{% hint style="info" %}
**Windows rootless feature flag**

The feature flag `CI_ADDON_LE_WINDOWS_ROOTLESS` downloads rootless **lite-engine**, **ci-addon**, and **drone-git** images for Windows by default. [Contact Harness Support](https://support.harness.io/) to enable this feature.
{% endhint %}

To use Windows images with a rootless operation, download the appropriate images. Use the following versions or later:

* `harness/ci-addon:rootless-1.16.92`
* `harness/ci-lite-engine:rootless-1.16.92`
* `harness/drone-git:1.6.9-rootless`

### Troubleshoot Harness CI images

<details>

<summary>List tags available for an image in the Harness image registry</summary>

To list all available tags for an image in `app.harness.io/registry`, call the following endpoint and replace `IMAGE_NAME` with the name of the image you want to query.

```
https://app.harness.io/registry/harness/IMAGE_NAME/tags/list
```

</details>

<details>

<summary>Resolve <code>ErrImagePull</code> errors</summary>

* **Error messages:** `ErrImagePull` or some variation of the following, which may have a different image name, tag, or registry: `Failed to pull image "artifactory.domain.com/harness/ci-addon:1.16.22": rpc error: code = Unknown desc = Error response from daemon: unknown: Not Found.`
* **Causes:**
  * Harness could not pull an image that is needed to run the pipeline.
  * `ErrImagePull` can be caused by networking issues or if the specified image does not exist in the specified repository.
  * `Failed to pull image - Not Found` means that a Harness-specific image or tag, in this case `ci-addon:1.16.22`, is not present in the specified artifact repository, and you are using the `account.harnessImage` connector to pull Harness images. You can use this connector to pull from your own registry or to pull images from any Docker registry, but it is also used to pull Harness-required CI images. Modifying this connector can cause it to fail to pull the necessary Harness CI images.
* **Solutions:**
  * If you modified the built-in Harness Docker connector, check the connector's configuration to make sure it uses one of the compatible methods for pull Harness-required images, as described in [Connect to the Harness container image registry](https://developer.harness.io/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/connect-to-harness-container-image-registry-using-docker-connector.md).
  * If you are trying to pull images from your own registry, check your configuration for [pulling Harness images from a private registry](https://developer.harness.io/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/connect-to-harness-container-image-registry-using-docker-connector.md#pull-harness-images-from-a-private-registry). You might need to use a different connecter than the built-in Harness Docker connector.
  * If you [modified tags for some images](#specify-the-harness-ci-images-used-in-your-pipelines), check that your configuration uses valid tags that are present in the repository from which Harness is attempting to pull the tags.
  * If you believe the issue is due to networking issues, try again later if you think the issue is transient, or check your connector or network configuration to make sure Harness is able to connect to the given registry.

</details>

<details>

<summary>Understand access to internal images</summary>

By default, Harness uses anonymous access to pull Harness images.

If you have security concerns about using anonymous access or pulling Harness-specific images from a public repo, you can [change how your builds connect to the Harness container image registry](https://developer.harness.io/harness-platform/use-harness-platform/connectors/artifact-repositories/add-a-docker-registry-connector/connect-to-harness-container-image-registry-using-docker-connector.md).

</details>

### Next steps

* [Pre-built public images](https://developer.harness.io/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/public-docker-images.md): Use pre-built public images for CI pipelines.
* [View CPU and memory utilization metrics](https://developer.harness.io/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/view-resource-utilization-metrics.md): Monitor real-time CPU, memory, and disk usage during CI pipeline execution on Harness Cloud.

{% @harness-feedback/feedback %}
