> 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/manage-dependencies/background-step-settings.md). # Background step settings Use Background steps to manage dependent services. Use Background steps to [manage dependent services](/continuous-integration/use-harness-ci/use-harness-ci/manage-dependencies/dependency-mgmt-strategies.md) that need to run for the entire lifetime of a Build stage. For example, you can set up your pipeline to run multiple background services that implement a local, multi-service app.

A Build stage with multiple services running in Background steps.

A Background step starts a service and then proceeds. For any later step that relies on the service, it is good practice to verify that the service is running before sending requests. {% hint style="info" %} * Background steps do not support failure strategies or output variables. * If the pipeline runs on a VM build infrastructure, you can run the background service directly on the VM rather than in a container. To do this, leave the **Container Registry** and **Image** fields blank. * Depending on the stage's build infrastructure, some settings might be unavailable, optional, or located under **Additional Configuration**. {% endhint %} ### Name and Id Enter a name summarizing the step's purpose. Harness automatically assigns an **Id** ([Entity Identifier Reference](/harness-platform/use-harness-platform/references/entity-identifier-reference.md)) based on the **Name**. You can change the **Id** until the step is saved; once saved, the **Id** is locked. {% hint style="info" %} If you are using a VM, local runner, or the Harness Cloud build infrastructure where the background step is running a container, you can use the Background step **Id** to call services started by Background steps in later steps, such as commands in Run steps. For example, a cURL command could call `BackgroundStepId:5000` where it might otherwise call `localhost:5000`. The Background step ID, pythonscript, is used in a cURL command in a Run step. If the Background step is inside a step group, you must include step group ID, such as `curl StepGroupId_BackgroundStepId:5000`, even if both steps are in the same step group. If the Background step runs directly on the host or in a Kubernetes cluster build infrastructure, do not use the step ID to reference Background steps. Instead, use `localhost:host_port`. For Background steps running MySQL in a Kubernetes cluster build infrastructure, you must use the IP and host port, such as `127.0.0.1:7001`. Go to [Port Bindings](#port-bindings) for more information. {% endhint %} ### Container Registry and Image The build environment must have the necessary binaries for the **Background** step to execute your test commands. Depending on the stage's build infrastructure, **Background** steps can use binaries that exist in the build environment, or use **Container Registry** and **Image** to pull an image, such as a public or private Docker image, that contains the required binaries. The stage's build infrastructure determines whether these fields are required or optional: * [Kubernetes cluster build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/k8s-build-infrastructure/set-up-a-kubernetes-cluster-build-infrastructure.md): **Container Registry** and **Image** are always required. * [Local runner build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/define-a-docker-build-infrastructure.md): **Run Tests** steps can use binaries available on the host machine. The **Container Registry** and **Image** are required if the machine does not have the binaries you need. * [Self-managed AWS/GCP/Azure VM build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/vm-build-infrastructure.md): **Run Tests** steps can use binaries that you have made available on your build VMs. The **Container Registry** and **Image** are required if the VM does not have the necessary binaries. These fields are located under **Additional Configuration** for stages that use self-managed VM build infrastructure. * [Harness Cloud build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md): **Run Tests** steps can use binaries available on Harness Cloud machines, as described in the [image specifications](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md#platforms-and-image-specifications). The **Container Registry** and **Image** are required if the machine does not have the binaries you need. These fields are located under **Additional Configuration** for stages that use Harness Cloud build infrastructure. **What are the expected values for Container Registry and Image** For **Container Registry** settings, provide a Harness container registry connector, such as a [Docker connector](broken://spaces/3F2TpHXhur2QtQnORSM9/pages/LZPXMHJjbQyZXdwC5Omo), that connects to a container registry, such as Docker Hub, where the **Image** is located. For **Image**, provide the FQN (fully-qualified name) or artifact name and tag of the Docker image to use when this step runs commands, for example `us-docker.pkg.dev/gar-prod-setup/harness-public/harness/cache:latest` or `maven:3.8-jdk-11`. If you do not include a tag, Harness uses the `latest` tag. Depending on the connector and feature flags set, **an FQN may be required**. You can use any Docker image from any Docker registry, including Docker images from private registries. Different container registries require different name formats, for example: * **Docker Registry:** Input the name of the artifact you want to deploy, such as `library/tomcat`. Wildcards are not supported. FQN is required for images in private container registries. * **ECR:** Input the FQN of the artifact you want to deploy. Images in repos must reference a path, for example: `40000005317.dkr.ecr.us-east-1.amazonaws.com/todolist:0.2`. * **GAR:** Input the FQN of the artifact you want to deploy. Images in repos must reference a path starting with the project ID that the artifact is in, for example: `us-docker.pkg.dev/gar-prod-setup/harness-public/harness/cache:latest`. ![](https://4226796345-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqKtVmwAGTfGQS1MVC97G%2Fuploads%2Fgit-blob-d85318ad66a11eb441aa3298dd35b0263632e296%2Frun-step-settings-03.png?alt=media) Configuring a Container Registry and Image settings. {% hint style="info" %} **REMOVE FQN REQUIREMENT** Customers who want to utilize non-FQN references for non public Docker-registry connectors will need to contact Harness Support to add the feature flags, `CI_REMOVE_FQN_DEPENDENCY_FOR_PRIVATE_REGISTRY_CONNECTOR_DOCKER` and `CI_REMOVE_FQN_DEPENDENCY`. {% endhint %} **Pulling images from JFrog Artifactory Docker registries** If you need to pull images from a JFrog Artifactory Docker registry, create a Docker connector that connects to your JFrog instance. **Do not use the Harness Artifactory connector** - The Artifactory connector only supports JFrog non-Docker registries. To create a Docker connector for a JFrog Docker registry: 1. Go to **Connectors** in your Harness project, organization, or account resources, and select **New Connector**. 2. Select **Docker Registry** under **Artifact Repositories**. 3. Enter a **Name** for the connector. The **Description** and **Tags** are optional. 4. For **Provider Type**, Select **Other**. 5. In **Docker Registry URL**, enter your JFrog URL, such as `https://mycompany.jfrog.io`. 6. In the **Authentication** settings, you must use **Username and Password** authentication. * **Username:** Enter your JFrog username. * **Password:** Select or create a [Harness text secret](/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md) containing the password corresponding with the **Username**. 7. Complete any other settings and save the connector. Go to the [Docker connector settings reference](broken://spaces/3F2TpHXhur2QtQnORSM9/pages/LZPXMHJjbQyZXdwC5Omo) for all Docker Registry connector settings. One completed, please remember to use the FQN location of the image unless you have set the [appropriate feature flags as listed above](#what-are-the-expected-values-for-container-registry-and-image) {% hint style="info" %} **JFROG URLS** The JFrog URL format depends on your Artifactory configuration, and whether your Artifactory instance is local, virtual, remote, or behind a proxy. To get your JFrog URL, you can select your repo in your JFrog instance, select **Set Me Up**, and get the repository URL from the server name in the `docker-login` command. ![](https://4226796345-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqKtVmwAGTfGQS1MVC97G%2Fuploads%2Fgit-blob-40ea99861b466b0e5c5011164f9c9d2922586a63%2Fartifactory-connector-settings-reference-09.png?alt=media) Go to the JFrog documentation on [Repository Management](https://www.jfrog.com/confluence/display/JFROG/Repository+Management) and [Configuring Docker Repositories](https://www.jfrog.com/confluence/display/RTF/Docker+Registry#DockerRegistry-ConfiguringDockerRepositories) for more information. {% endhint %}

An example configuration for the Container Registry and Image fields. Note that this figure shows a Run step, but the fields are populated the same for Background steps.

{% hint style="info" %} The stage's build infrastructure determines whether these fields are required or optional: * [Kubernetes cluster build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/k8s-build-infrastructure/set-up-a-kubernetes-cluster-build-infrastructure.md): **Container Registry** and **Image** are always required. * [Local runner build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/define-a-docker-build-infrastructure.md): **Background** steps can use binaries available on the host machine. The **Container Registry** and **Image** are required if the machine does not have the binaries you need. * [Self-managed AWS/GCP/Azure VM build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/vm-build-infrastructure.md): **Background** steps can use binaries that you have made available on your build VMs. The **Container Registry** and **Image** are required if the VM does not have the necessary binaries. These fields are located under **Optional Configuration** for stages that use self-managed VM build infrastructure. * [Harness Cloud build infrastructure](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md): **Background** steps can use binaries available on Harness Cloud machines, as described in the [image specifications](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/use-harness-cloud-build-infrastructure.md#platforms-and-image-specifications). The **Container Registry** and **Image** are required if the machine does not have the binary you need. These fields are located under **Optional Configuration** for stages that use Harness Cloud build infrastructure. {% endhint %} ### Shell, Entry Point, and Command Use these fields to define the commands that you need to run in the Background step. #### Shell Select the shell type for the commands defined in **Entry Point** or **Command**. Options include: **Bash**, **PowerShell**, **Pwsh** (PowerShell Core), **Sh**, and **Python**. If the step includes commands that are not supported for the selected shell type, the build fails. Required binaries must be available on the build machine or through a specified [Container Registry and Image](#container-registry-and-image). #### Entry Point Supply a list of arguments in `exec` format. **Entry Point** arguments override the image `ENTRYPOINT` and any commands in the **Command** field. Enter each argument separately. If you want to add your **Entry Point** arguments to the image `ENTRYPOINT`, include both the image `ENTRYPOINT`, such as `dockerd-entrypoint.sh`, and your additional arguments in **Entry Point**. {% tabs %} {% tab title="Visual" %}

Entry Point arguments in the Pipeline Studio Visual editor.

{% endtab %} {% tab title="YAML" %} ```yaml entrypoint: - dockerd-entrypoint.sh - "--mtu=1450" ``` {% endtab %} {% endtabs %} {% hint style="info" %} In a Kubernetes cluster build infrastructure, you can use **Entry Point** to override port mappings when [running multiple PostgreSQL instances in Background steps](/continuous-integration/use-harness-ci/use-harness-ci/manage-dependencies/multiple-postgres.md). {% endhint %} #### Command Enter [POSIX](https://en.wikipedia.org/wiki/POSIX) shell script commands (beyond the image `ENTRYPOINT`) for this step. If the step runs in a container, the commands are executed inside the container. {% tabs %} {% tab title="Bash" %} This Bash script example checks the Java version. ```yaml - step: ... spec: shell: Bash command: |- JAVA_VER=$(java -version 2>&1 | head -1 | cut -d'"' -f2 | sed '/^1\./s///' | cut -d'.' -f1) if [[ $JAVA_VER == 17 ]]; then echo successfully installed $JAVA_VER else exit 1 fi ``` {% endtab %} {% tab title="PowerShell" %} This is a simple PowerShell `Wait-Event` example. ```yaml - step: ... spec: shell: Powershell command: Wait-Event -SourceIdentifier "ProcessStarted" ``` {% hint style="info" %} You can run PowerShell commands on Windows VMs running in AWS build farms. {% endhint %} {% endtab %} {% tab title="Pwsh" %} This PowerShell Core example runs `ForEach-Object` over a list of events. ```yaml - step: ... spec: shell: Pwsh command: |- $Events = Get-EventLog -LogName System -Newest 1000 $events | ForEach-Object -Begin {Get-Date} -Process {Out-File -FilePath Events.txt -Append -InputObject $_.Message} -End {Get-Date} ``` {% hint style="info" %} You can run PowerShell Core commands in pods or containers that have `pwsh` installed. {% endhint %} {% endtab %} {% tab title="Sh" %} In this example, the pulls a `python` image and executes a shell script (`Sh`) that runs `pytest` with code coverage. ```yaml - step: ... spec: connectorRef: YOUR_IMAGE_REGISTRY_CONNECTOR image: python:latest shell: Sh command: |- echo "Welcome to Harness CI" uname -a pip install pytest pip install pytest-cov pip install -r requirements.txt pytest -v --cov --junitxml="result.xml" test_api.py test_api_2.py test_api_3.py ``` {% endtab %} {% tab title="Python" %} If the `shell` is `Python`, supply Python commands directly in `command`. This example uses a basic `print` command. ``` steps: - step: ... spec: shell: Python command: print('Hello, world!') ``` {% endtab %} {% endtabs %} {% hint style="info" %} You can use `docker-compose up` to start multiple services in one Background step. {% endhint %} ### Privileged Select this option to run the container with escalated privileges. This is the equivalent of running a container with the Docker `--privileged` flag. ### Report Paths The path to the files that store [results in JUnit XML format](/continuous-integration/use-harness-ci/use-harness-ci/run-tests/test-report-ref.md). You can add multiple paths. If you specify multiple paths, make sure the files contain unique tests to avoid duplicates. [Glob](https://en.wikipedia.org/wiki/Glob_\(programming\)) is supported. This setting is required for commands run in the Background step to be able to [publish test results](/continuous-integration/use-harness-ci/use-harness-ci/run-tests/viewing-tests.md). ### Environment Variables You can inject environment variables into the step container and use them in the **Command** script. You must input a **Name** and **Value** for each variable. You can reference environment variables in the **Command** script by name. For example, a Bash script would use `$var_name` or `${var_name}`, and a Windows PowerShell script would use `$Env:varName`. Variable values can be [fixed values, runtime inputs, or expressions](/harness-platform/use-harness-platform/variables-and-expressions/runtime-inputs.md). For example, if the value type is expression, you can input a value that references the value of some other setting in the stage or pipeline.

Using an expression for an environment variable's value.

{% hint style="info" %} **STAGE VARIABLES** [Stage variables](/harness-platform/use-harness-platform/pipelines/add-a-stage.md#stage-variables) are inherently available to steps as environment variables. {% endhint %} ### Image Pull Policy If the service is running in a container, you can select an option to set the pull policy for the image. * **Always**: The kubelet queries the container image registry to resolve the name to an image digest every time the kubelet launches a container. If the kubelet encounters an exact digest cached locally, it uses its cached image; otherwise, the kubelet downloads (pulls) the image with the resolved digest, and uses that image to launch the container. * **If Not Present**: The image is pulled only if it is not already present locally. * **Never**: The image is assumed to exist locally. No attempt is made to pull the image. ### Port Bindings The host port and container port binding are similar to [port mapping in Docker](https://docs.docker.com/config/containers/container-networking/). Usually the ports are the same unless the default host port for the Background step is already in use by another local service or you are [running multiple instances of the same service](/continuous-integration/use-harness-ci/use-harness-ci/manage-dependencies/multiple-postgres.md). Depending on the Build stage's **Infrastructure**, some steps might run directly on VMs while other steps run in containers. The port used to communicate with a service started by a Background step depends on where the step is running. For example, assume you create a Background step with the [Name and ID](#name-and-id) `myloginservice`. To call this service in later steps in the same stage, you use: * `myloginservice:container_port` for containerized steps, such as those running in self-managed VM build infrastructures or running Docker images. * `localhost:host_post` for steps running in a Kubernetes cluster build infrastructure or directly on the build machine (such as a service running from a binary already installed on the host machine). For steps running MySQL in a Kubernetes cluster build infrastructure, you must use `127.0.0.1:host_port`. {% hint style="info" %} **SERVICE BINDING INSIDE THE CONTAINER** If your application binds only to `127.0.0.1` inside the container, it will not be reachable from outside the container — even if you configure Port Bindings in Harness.\ To make the service accessible, ensure the application listens on `0.0.0.0`. This binds the service to all available network interfaces inside the container, allowing Docker’s `-p` port mapping (or Harness Port Bindings) to expose it. For example, in a Node.js service: ```js app.listen(8080, "0.0.0.0", () => { console.log("Listening..."); }); ``` {% endhint %} {% hint style="info" %} If your build stage uses Harness Cloud build infrastructure and you are running a Docker image in a Background step, you must specify **Port Bindings** if you want to reference that Background step in a later step in the pipeline (such as in a cURL command in a Run step). Go to [Name and Id](#name-and-id) for referencing background services in other steps. {% endhint %} ### Run as User If the service is running in a container, you can specify the user ID to use for all processes in the pod. Go to [Set the security context for a pod](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod) for how to set the value. ### Set Container Resources The maximum memory and cores that the container can use. * **Limit Memory:** The maximum memory that the container can use. You can express memory as a plain integer or as a fixed-point number using the suffixes `G` or `M`. You can also use the power-of-two equivalents `Gi` and `Mi`. Do not include spaces when entering a fixed value. The default value is `500Mi`. * **Limit CPU:** The maximum number of cores that the container can use. CPU limits are measured in CPU units. Fractional requests are allowed; for example, you can specify one hundred millicpu as `0.1` or `100m`. The default is `400m`. Go to [Resource units in Kubernetes](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) for more information. ### Troubleshoot Background steps Go to the [CI Knowledge Base](/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md) for questions and issues related to Background steps, including: * [Do Background steps have limitations?](/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#do-background-steps-have-limitations) * [Can Background steps run multiple services simultaneously?](/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#can-background-steps-run-multiple-services-simultaneously) * [How can a step call a service started by a Background step?](/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#how-can-a-step-call-a-service-started-by-a-background-step) * [I can't connect to the hostname using the step ID from my Background step, and I get an "Unknown server host" error](/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#i-cant-connect-to-the-hostname-using-the-step-id-from-my-background-step-and-i-get-an-unknown-server-host-error) * [Why is Background step always marked as successful even if there are failures executing the entry point?](/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#why-is-background-step-always-marked-as-successful-even-if-there-are-failures-executing-the-entry-point) * [How can I health check services running in Background steps?](/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#how-can-i-make-sure-my-background-service-is-healthy-before-running-the-rest-of-my-pipeline-how-can-i-test-that-my-background-service-is-running) {% @harness-feedback/feedback %}