Skip to main content

CI Build stage settings

This topic describes CI Build stage settings. For more information about configuring stages in CI pipelines, go to CI pipeline creation overview.

To create, edit, and delete stages in CI pipelines, you need either Project Admin or Project Member permissions. For more information, go to the Permission Reference.

Add a Build stage to a pipeline​

  1. In Harness, edit or create a pipeline.

  2. Select Add Stage, and then select Build.

  3. In Stage Name, enter a name summarizing the stage's purpose.

    Harness automatically assigns an Id (Entity Identifier Reference) based on the Name. You can change the Id when you first add the stage. After you add the stage, it the Id can't be changed.

    The description and tags are optional.

  4. Configure the default codebase settings.

    • Clone Codebase: When enabled, Harness automatically clones the codebase, specified by the Connector and Repository URL, before executing the steps in the stage. If disabled, Harness doesn't clone a codebase when initializing the stage.
    • Connector: A Harness code repo connector that connects to the repository where the codebase is located. For information about code repo connectors and the default codebase configuration, go to Create and configure a codebase.
    • Repository URL: If not populated automatically, enter the full URL to the code repository that you want the pipeline to use.

    The codebase Connector and Repository URL settings are available when you add the first stage to a pipeline. After you add the first stage, you manage these in the pipeline's Codebase settings (not the stage's settings). For more information, go to Edit the default codebase configuration.

  5. Select Set Up Stage.

  6. Select the Overview, Infrastructure, Execution, and Advanced tabs to configure the stage settings, set up the build infrastructure, and add steps to the stage.

Overview​

These settings are found on the Overview tab after adding a Build stage to a pipeline.

Stage Details​

You can edit the Name, Description, and Tags. You can also toggle the Clone Codebase setting for this stage.

Shared Paths​

You can use Shared Paths to specify paths to folders outside the default workspace. You can use this to share data across steps or customize cache paths for Cache Intelligence.

When a pipeline runs, it creates a temporary volume called a workspace. During initialization, the stage clones your codebase to the root of the workspace. Then, the steps in the stage run inside the root. The workspace is the current working directory for each step in the stage. The workspace persists for the lifetime of the stage and enables steps in that stage to communicate and share state information. The default shared working directory for a stage is /harness. The workspace is destroyed when the stage ends.

Individual steps can communicate and share state using the workspace filesystem. The workspace is a volume, so filesystem changes persist throughout the stage lifetime. If you need to share additional volumes, you can add Shared Paths. Path declarations must begin with a forward slash, such as /vol.

For example, the maven m2 repo is stored in /root/.m2 by default. If your Build stage uses Maven, you can specify /root/.m2 as a Shared Path so that all steps in that stage can access that directory.

Cache Intelligence​

You can enable and configure Cache Intelligence. This feature is only available for Linux and Windows platforms on Harness Cloud build infrastructure.

For fully supported build tools with dependencies stored in the default location for the tool used, you only need to select Enable Cache Intelligence.

For other build tools or non-default cache locations, you must provide custom cache Paths in addition to enabling Cache Intelligence. Depending on the cache location, you might also need to specify these paths in Shared Paths.

Optionally, you can specify a custom cache Key

For information about supported tools, enabling cache intelligence, and configuring custom cache paths and keys, go to the Cache Intelligence documentation.

SLSA Provenance​

These settings are for the Harness SSCA module.

Advanced: Stage Variables​

Stage variables are available to all steps in the stage. There are many uses for these variables. For some examples, go to:

Infrastructure​

These settings are found on the Infrastructure tab after adding a stage to a pipeline.

Infrastructure is where the build runs the steps in this stage. It is a build farm, such as a Kubernetes cluster. Infrastructure settings vary by build infrastructure type.

The first stage requires you to configure a build infrastructure. In stages after the first, you can either Propagate from an existing stage or Use a New Infrastructure.

Use the Kubernetes infrastructure option to set up a Kubernetes cluster build infrastructure.

The following Platform settings are available:

  • Select the Operating System: Select the relevant OS.
  • Kubernetes Cluster: Select a Kubernetes cluster connector.
  • Namespace: Enter the Kubernetes namespace to use in the target cluster. You can also use a Runtime Input (<+input>) or expression for the namespace. For more information, go to Runtime Inputs.

The following Advanced settings are available for the Kubernetes infrastructure:

Volumes​

You can add a list of volumes you want to mount onto the pod where the stage runs.

  • Mount Path: Enter the path to the volume.
  • Type: Select Empty Directory, Host Path, or Persistent Volume Claim.
  • If Type is Empty Directory, you can specify the storage Medium and volume's maximum memory Size.
  • If Type is Host Path, you must specify Path and you can specify an optional Path Type.
  • If Type is Persistent Volume Claim, you must specify a Claim Name and whether the volume is Read Only.

The following YAML example shows two Empty Directory volumes that would be used for PostgreSQL data.

            spec:
              connectorRef: YOUR_K8S_CLUSTER_CONNECTOR_ID
              namespace: YOUR_K8S_CLUSTER_NAMESPACE
              volumes:
                - mountPath: /tmp/pgdata1
                  type: EmptyDir
                  spec:
                    medium: ""
                - mountPath: /tmp/pgdata2
                  type: EmptyDir
                  spec:
                    medium: ""

Service Account Name​

Specify a Kubernetes service account that you want step containers to use when communicating with the Kubernetes API server. Leave this field blank if you want to use the namespace's default service account. You must set this field in the following cases:

  • Your build infrastructure runs on EKS, you have an IAM role associated with the service account, and the stage has a step that uses a Harness AWS connector with IRSA. For more information, go to the AWS documentation on IAM Roles for Service Accounts.
  • Your Build stage has steps that communicate with any external services using a service account other than the default. For more information, go to the Kubernetes documentation on Configure Service Accounts for Pods.
  • Your Kubernetes cluster connector inherits authentication credentials from the Delegate.

Automount Service Account Token​

By default, this option is selected and Kubernetes mounts a token for the Service Account when it creates a pod, which enables the pod to communicate with the Kubernetes API server. When this option is not selected, the service account token is not mounted.

Labels​

You can add Kubernetes labels, as key-value pairs, to the pods in your infrastructure. Labels are useful for searching, organizing, and selecting objects with shared metadata. You can find pods associated with specific stages, organizations, projects, pipelines, builds, or any custom labels you want to query, for example:

kubectl get pods -l stageID=mycibuildstage

For more information, go to the Kubernetes documentation on Labels and Selectors.

Custom label values must the following regex in order to be generated:

^[a-z0-9A-Z][a-z0-9A-Z\\-_.]*[a-z0-9A-Z]$

Harness adds the following labels automatically:

  • stageID: See pipeline.stages.stage.identifier in the Pipeline YAML.
  • stageName: See pipeline.stages.stage.name in the Pipeline YAML.
  • orgID: See pipeline.orgIdentifier in the Pipeline YAML.
  • projectID: See pipeline.projectIdentifier in the Pipeline YAML.
  • pipelineID: See pipeline.identifier in the Pipeline YAML.
  • pipelineExecutionId: To find this, go to a CI Build in the Harness UI. The pipelineExecutionID is near the end of the URL path, between executions and /pipeline, for example:
https://app.harness.io/ng/#/account/myaccount/ci/orgs/myusername/projects/myproject/pipelines/mypipeline/executions/__PIPELINE_EXECUTION-ID__/pipeline

Annotations​

You can add Kubernetes annotations to the pods in your infrastructure. An annotation can be small or large, structured or unstructured, and can include characters not permitted by labels. For more information, go to the Kubernetes documentation on Annotations.

Container Security Context​

Configure the Security Context for the stage (pod) and steps (containers):

  • Privileged: Run all containers with the --privileged flag enabled. This flag is disabled by default. You can override this setting in individual Run and Run Tests steps.
  • Allow Privilege Escalation: When enabled, a process can gain more privileges than its parent process. This setting determines whether the no_new_privs flag gets set on the container process.
  • Add Capabilities: The list of capabilities to add to each step by default, in addition to the runtime defaults. This field corresponds to the capabilities: add option in Kubernetes.
  • Drop Capabilities: The list of capabilities that must be dropped from each step. This field corresponds to the capabilities: drop option in Kubernetes.
  • Read-Only Root Filesystem: Run all steps with a read-only root filesystem that has no writable layer.
  • Run as Non-Root and Run as User: Go to Run as non-root or a specific user.

Run as non-root or a specific user​

You can use the Run as Non-Root and Run as User settings to run builds as a non-root user or a specific user ID.

caution

Using a non-root user can require other changes to your pipeline.

With a Kubernetes cluster build infrastructure, all Build and Push steps use kaniko. This tool requires root access to build the Docker image. It doesn't support non-root users.

If you enable Run as Non-Root, then you must:

  • Run the Build and Push step as root by setting Run as User to 0 on the Build and Push step. This will use the root user for that individual step only.
  • If your security policy doesn't allow running as root for any step, you must use the Buildah Drone plugin to build and push with non-root users.
  • Run as Non-Root: Enable this option to run all steps as a non-root user. If enabled, you must specify a default user ID for all containers in the Run as User field.
  • Run as User: Specify a user ID, such as 1000, to use for all containers (steps) in the pod (stage). You can also set Run as User values for individual steps. If you set Run as User on a step, it overrides the build infrastructure Run as User setting.

Priority Class​

Set the Build stage pod's PriorityClass in case there are resource shortages the host node. You can specify a PriorityClass from your build infrastructure or use the predefined classes system-cluster-critical or system-node-critical, which ensure that the stage is always scheduled first.

If you leave this field blank, the PriorityClass is set to the globalDefault, if your infrastructure has one defined, or 0, which is the lowest priority.

Node Selector​

A list of nodeSelectors, which whitelist the set of candidate nodes based on your stage pod's requirements.

Tolerations​

A list of tolerations that allow (but do not require) Build stage pods to be scheduled onto nodes with matching taints. For example:

              tolerations:
                - effect: NoSchedule
                  key: key1
                  operator: Equal
                  value: value1
                - effect: NoSchedule
                  key: key2
                  operator: Equal
                  value: value2

Multiple tolerations with the same key​

Keys are reserved keywords used to validate unique FQNs. If you have multiple tolerations with the same key, you must include an identifier to differentiate them. For example:

              tolerations:
                - identifier: identifier1
                  effect: NoSchedule
                  key: key1
                  operator: Equal
                  value: value1
                - identifier: identifier2
                  effect: NoSchedule
                  key: key1
                  operator: Equal
                  value: value2

Host Names​

A list of HostAliases to set pod-level override of hostname resolution.

Init Timeout​

Set the timeout for the initialization phase. During this phase, Harness downloads the build step images and spins up the containers to execute the build steps.

If you use large images in your Build stage's steps, you might find that the initialization step times out and the build fails when the pipeline runs. In this case, you can increase the init timeout window from the default of 8 minutes.

Override Image Connector​

By default, Harness pulls certain images from public Docker Hub repos that are needed to run a build. You can override this by using a Docker connector that downloads the images from the Harness Container Image Registry instead. This option is useful when your default Delegate cannot access the public registry (for example, due to security policies in your organization or if your infrastructure is running in a private cloud).

Execution​

The Execution tab is where you add steps to the stage. For details about different step types, go to:

Advanced​

The Advanced tab contains settings for conditional execution, looping strategies, and failure strategies.