Skip to main content

Use the GitHub Action step

GitHub Actions is a GitHub feature that enables you to automate various event-driven activities in GitHub, such as cloning a repository, generating Docker images, and testing scripts. You can find over 10,000 GitHub Actions on the GitHub Marketplace or create your own Actions.

You can use the GitHub Action plugin step (also called the GitHub Action step or Action step) to run GitHub Actions in your Harness CI pipelines.

info

Currently, the GitHub Action step is supported for Harness Cloud build infrastructure only.

For other build infrastructures, you can use the GitHub Actions Drone plugin in a Plugin step.

For more information about using plugins in CI pipelines, go to Explore plugins.

Action step usage examples​

The following YAML examples use GitHub Action steps (Action steps) to set up Node.js, Go, Java, and Ruby environments.

This Action step uses the actions/setup-node GitHub Action to set up a Node.js environment that the subsequent steps in the stage can use.

              - step:
                  type: Action
                  name: setup nodejs
                  identifier: setup_nodejs
                  spec:
                    uses: actions/setup-node@v3
                    with:
                      node-version: '16'

Action step settings and specifications​

To add a GitHub Action step in the YAML editor, add an Action step, for example:

              - step:
                  type: Action
                  name: setup golang
                  identifier: setup_go
                  spec:
                    uses: actions/setup-go@v3
                    with:
                      go-version: '1.17'

The spec parameters define which Action to use, the Action settings, and environment variables that you need to pass to the Action. These are configured according to the GitHub Action's usage specifications.

  • uses: Specify the Action's repo, along with a branch or tag, such as actions/stepup-go@v3.
  • with: If required by the Action, provide a mapping of key-value pairs representing Action settings, such as go-version: '1.17'.
  • env: If required by the Action, provide a mapping of environment variables to pass to the Action. Note that env specifies incoming environment variables, which are separate from outgoing environment variables that may be output by the Action.

The following cases always require environment variables (env):

Tips
  • If you already configured GitHub Actions elsewhere, you can quickly transfer GitHub Actions into Harness CI by copying the spec details from your existing GitHub Actions YAML.
  • You can use variable expressions in the with and env settings. For example, credentials: <+stage.variables.[TOKEN_SECRET]> uses a stage variable to call a token stored as a Harness secret.
  • For GitHub Actions steps, with mappings are automatically exported as output variables.
YAML example: Pipeline with an Action step

This pipeline uses a GitHub Action step to install golang version 1.19.5. It then compiles the golang application and runs tests.

pipeline:
  name: Build and test golang application
  identifier: Build_test_golang
  projectIdentifier: default
  orgIdentifier: default
  tags: {}
  properties:
    ci:
      codebase:
        connectorRef: YOUR_CODEBASE_CONNECTOR_ID
        build: <+input>
  stages:
    - stage:
        name: Build golang application
        identifier: Build_golang_application
        description: ""
        type: CI
        spec:
          cloneCodebase: true
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          execution:
            steps:
              - step:
                  type: Action
                  name: setup golang
                  identifier: setup_go
                  spec:
                    uses: actions/setup-go@v3
                    with:
                      go-version: 1.19.5
              - step:
                  type: Run
                  name: Build and test
                  identifier: Build_and_test
                  spec:
                    shell: Bash
                    command: |-
                      go build .
                      go test -v ./...

Private Action repositories​

If you want to use an Action that is in a private repository, you must provide the GITHUB_TOKEN environment variable. You need a GitHub personal access token that has pull permissions to the target repository. Additional permissions may be necessary depending on the Action's purpose.

In the YAML editor, add GITHUB_TOKEN to the env mapping, for example:

- step:
    type: Action
    name: hello world
    identifier: hello_world
    spec:
      uses: my-actions-repo/hello-world-javascript-action@main
      with:
        who-to-greet: 'Mona the Octocat'
      env:
        GITHUB_TOKEN: <+secrets.getValue("[SECRET_NAME]")>
tip

You can use a variable expressions, such as <+secrets.getValue("[SECRET_NAME]")>, to call a token stored as a Harness Secret.

For more information about configuring the Action step's settings, go to the Action step settings and specifications section, above.

Duplicate Actions​

If you run multiple instances of the same GitHub Action, either in parallel or with a looping strategy, you must set the XDG_CACHE_HOME environment variable.

The default value of this variable is /home/ubuntu/.cache; however, the XDG_CACHE_HOME variable must have a different value for each instance of the Action. If you have separate steps running in parallel, assign distinct values to each step, such as XDG_CACHE_HOME: /home/ubuntu/.cache1. If you apply a looping strategy to repeat one step multiple times, you can use an expression to generate distinct values, such as XDG_CACHE_HOME: /home/ubuntu/.cache<+step.identifier>.

In this example, two parallel Action steps run the same GitHub Action. Each step has a unique value for XDG_CACHE_HOME.

            steps:
              - parallel
                  - step:
                      type: Action
                      name: gcsuploader
                      identifier: gcsuploader
                      spec:
                        uses: google-github-actions/upload-cloud-storage@main
                        with:
                          path: pom.xml
                          destination: cie-demo-pipeline/target
                          credentials: <+stage.variables.GCP_SECRET_KEY_BASE64>
                         env:
                          XDG_CACHE_HOME: /home/ubuntu/.cache1
                  - step:
                      type: Action
                      name: gcsuploader2
                      identifier: gcsuploader2
                      spec:
                        uses: google-github-actions/upload-cloud-storage@main
                        with:
                          path: pom.xml
                          destination: cie-prod-pipeline/target
                          credentials: <+stage.variables.GCP_SECRET_KEY_BASE64>
                         env:
                          XDG_CACHE_HOME: /home/ubuntu/.cache2

Actions requiring a defined working directory​

Some GitHub Actions need to run on the cloned codebase. The Action step doesn't automatically set a working directory.

If this is required by the Action you want to run, and the Action offers a working directory parameter, then you need to specify the working directory as /harness. For example:

              - step:
                  type: Action
                  name: Action docker publish image
                  identifier: Action_docker_publish_image
                  spec:
                    uses: elgohr/Publish-Docker-Github-Action@v4
                    with:
                      name: dockerhub/publish-docker-image
                      username: ${{ secrets.DOCKER_USERNAME }}
                      password: ${{ secrets.DOCKER_PASSWORD }}
                      workdir: /harness

If the Action ingests the working directory as an environment variable, place it under env.

If the Action doesn't offer a way to set a working directory, it most likely won't run in Harness.

Output variables from GitHub Actions steps​

Output variables are exposed values that can be used by other steps or stages in the pipeline. For GitHub Actions steps, Settings (with) values are automatically exported as output variables, and you can fetch those values in later steps or stages in the same pipeline.

To reference an output variable in another step in the same stage, use either of the following expressions:

<+steps.STEP_ID.output.outputVariables.VAR_NAME>
<+execution.steps.STEP_ID.output.outputVariables.VAR_NAME>

To reference an output variable in a stage other than the one where the output variable originated, use either of the following expressions:

<+stages.STAGE_ID.spec.execution.steps.STEP_ID.output.outputVariables.VAR_NAME>
<+pipeline.stages.STAGE_ID.spec.execution.steps.STEP_ID.output.outputVariables.VAR_NAME>

For each expression:

  • Replace STEP_ID with the ID of the GitHub Actions step
  • Replace VAR_NAME with the relevant variable name, wrapped in quotes.
  • In cross-stage references, replace STAGE_ID with the ID of the stage where the GitHub Actions step exists.
warning

GitHub Actions settings keys can include -, which is not supported by JEXL. Therefore, you must wrap these variable names in quotes when using them in Harness expressions.

YAML example: GitHub Actions output variable

In the following YAML example, the setup_go step uses a go-version setting, which is automatically exported as an output variable. The beta step includes two expressions referencing the go-version output variable.

              - step:
                  type: Action
                  name: setup golang
                  identifier: setup_go
                  spec:
                    uses: actions/setup-go@v3
                    with:
                      go-version: `1.17`
              - step:
                  type: Run
                  name: beta
                  identifier: beta
                  spec:
                    shell: Sh
                    command: |-
                      echo <+steps.setup_go.output.outputVariables."go-version">
                      echo <+execution.steps.setup_go.output.outputVariables."go-version">

Transfer GitHub Actions into Harness CI​

If you already configured GitHub Actions elsewhere, you can copy the uses, with and env lines from your GitHub Action YAML into the Action step's spec in your Harness CI pipeline YAML.

If you're using the Visual editor, you can transfer the data into the Uses, Settings, and Environment Variables fields.

The following table compares GitHub Action YAML with Harness CI Action step YAML. Notice the consistency of uses, with, and env.

GitHub Action YAMLHarness CI Action step YAML
- name: hello-world
  uses: actions/hello-world-javascript-action@main
  with:
    who-to-greet: 'Mona the Octocat'
  env:
    hello: world
- step:
    type: Action
    name: hello world
    identifier: hello_world
    spec:
      uses: actions/hello-world-javascript-action@main
      with:
        who-to-greet: 'Mona the Octocat'
      env:
        hello: world

Troubleshooting GitHub Actions in Harness CI​

Go to the CI Knowledge Base for questions and issue related to plugins and integrations, including GitHub Action steps. For example: