Run a script in a Build stage

You can use a CI Run step to run scripts and commands in Build stages in CI pipelines. Here are a few examples of ways you could use Run steps:

• Pull the Docker image for Maven and then run the mvn package command with that tool.
• Run tests with pytest.
• Run a simple echo or sleep command.
• Set up an environment or specify a version, such as sudo xcode-select -switch /Applications/Xcode_14.1.0.app.

Depending on the stage's build infrastructure, a Run step can use binaries that exist in the build environment or pull an image, such as a public or private Docker image, that contains the required binaries.

• Kubernetes cluster build infrastructure: Image always required.
• Local runner build infrastructure: Image always required.
• Self-hosted cloud provider VM build infrastructure: Run steps can use binaries that you've made available on your build VMs. An image is required if the VM doesn't have the necessary binaries.
• Harness Cloud build infrastructure: Run steps can use binaries available on Harness Cloud machines, as described in the image specifications. An image is required if the machine doesn't have the binary you need.

Requirements

This topic assumes you are familiar with the following:

• CI pipeline concepts
• CI Build Stage Settings
• Creating and configuring codebases for CI pipelines

You need a CI pipeline to which you can add the Run step.

Prepare your pipeline

You need a CI pipeline with a Build stage that is connected to your codebase. If you haven't created a pipeline before, try one of the CI pipeline tutorials.

To add a Build stage to an existing pipeline:

1. Go to the pipeline you want to edit.
2. In the Pipeline Studio, select Add Stage, and then select Build.
3. Enter a Stage Name, enable Clone Codebase, and then select Set Up Stage.
4. Select the Infrastructure tab and set up the build infrastructure.

To check codebase configuration for existing pipelines, select Codebase while viewing the pipeline in the Pipeline Studio. For more information about codebase configuration, go to Edit Codebase Configuration.

Add the Run step

Visual

1. Go to the Build stage in the pipeline where you want to add the Run step.

2. Select Add Step, select Add Step again, and then select Run in the Step Library.

3. Enter a Name and optional Description.

4. Depending on the stage's build infrastructure, specify the Container Registry and Image containing the binaries that the step needs to run your script. For example, a cURL script may require a cURL image, such as curlimages/curl:7.73.0. For information about when these fields are required and how to specify images, go to the Run step settings reference.

5. Select the Shell type and input your script in the Command field.

6. Populate other Run step settings as necessary. For example:

   • If your script runs tests, you might specify Report Paths.
   • If your script requires a token or secret, you might need to supply the token as an Environment Variable.
   • If you script produces an output variable value, you must declare the variable name in Output Variables.

7. Select Apply Changes to save the step, and then select Save to save the pipeline.

YAML

In Harness, go to the pipeline where you want to add the Run step. In the CI stage, add a Run step.

For all build infrastructures, you must specify type, name, identifier, shell, and command. The following examples shows the minimum settings for a Run step.

              - step:
                  type: Run
                  name: Run pytest # Specify a name for the step.
                  identifier: Run_pytest # Define a step ID, usually based on the name.
                  spec:
                    shell: Sh
                    command: |-
                      # Enter commands/script.

Depending on your build infrastructure and the commands you are running, connectorRef and image might be required. These settings define a container registry connector and image containing the binaries that the step needs to run your script. For example, a cURL script might require a cURL image, such as curlimages/curl:7.73.0. For information about when these settings are required and how to specify images, go to the Run step settings reference.

The following example shows a Run step with connectorRef and image.

              - step:
                  type: Run
                  name: Run pytest # Specify a name for the step.
                  identifier: Run_pytest # Define a step ID, usually based on the name.
                  spec:
                    connectorRef: account.harnessImage # Specify a container registry, if required.
                    image: python:latest # Specify an image, if required.
                    shell: Sh
                    command: |-
                      # Enter a command or script.

Define other Run step settings as necessary. For example:

• If your script runs tests, you might specify reports.
• If your script requires a token or secret, you might need to supply the token in envVariables.
• If your script produces an output variable value, you must declare the variable name in outputVariables.

The following example includes reports settings and commands that run pytest with code coverage.

              - step:
                  type: Run
                  name: Run pytest # Specify a name for the step.
                  identifier: Run_pytest # Define a step ID, usually based on the name.
                  spec:
                    connectorRef: account.harnessImage # Specify a container registry, if required.
                    image: python:latest # Specify an image, if required.
                    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

                      echo "Done"
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - "**/*.xml"

Run the Pipeline

Select Run to run the pipeline. Depending on your codebase configuration, you may need to specify a branch or tag.

While the build runs, you can observe the step logs on the Build details page.

After the pipeline runs, you can view test reports on the Tests tab of the Build details page.

tip

For an example of a Run step that runs tests and produces test reports, go to the Code coverage with CodeCov in Harness CI tutorial.