Skip to main content

Use the GitHub Action plugin 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 to run GitHub Actions in your Harness CI pipelines.

info

Currently, the GitHub Action plugin step is supported for the 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.

Usage examples​

The following YAML examples use GitHub Action plugin 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'

Settings and specifications​

To add a GitHub Action plugin 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:

  • Private Action repos: For private Action repositories, you must provide the GITHUB_TOKEN environment variable, such as GITHUB_TOKEN: <+secrets.getValue("[SECRET_NAME]")>. You need a GitHub personal access token that has pull permissions to the target repository. Additional permissions may be required, depending on the Action's purpose.
  • 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 iteration 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 the same step, you can use an expression to generate distinct values, such as XDG_CACHE_HOME: /home/ubuntu/.cache<+step.identifier>.
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 plugin 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 Settings and specifications section, above.

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.[stepID].output.outputVariables.[varName]>
<+execution.steps.[stepID].output.outputVariables.[varName]>

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

<+stages.[stageID].spec.execution.steps.[stepID].output.outputVariables.[varName]>
<+pipeline.stages.[stageID].spec.execution.steps.[stepID].output.outputVariables.[varName]>

For each expression:

  • Replace [stepID] with the ID of the GitHub Actions step
  • Replace [varName] with the relevant variable name, wrapped in quotes.
  • In cross-stage references, replace [stageID] with the ID of the stage where the GitHub Actions step exists.
caution

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 YAML Harness 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: Can't connect to Docker daemon​

Error messages like cannot connect to the Docker daemon indicate that you might have multiple steps attempting to run Docker at the same time. This can occur when running GitHub Actions in stages that have Docker-in-Docker (DinD) Background steps.

Actions that launch DinD: You can't use GitHub Actions that launch DinD in the same stage where DinD is already running in a Background step. If possible, run the GitHub Action in a separate stage or try to find a GitHub Action that doesn't use DinD.

Actions that launch the Docker daemon: If your Action attempts to launch the Docker daemon, and you have a DinD Background step in the same stage, you must add PLUGIN_DAEMON_OFF: true as a stage variable. For example:

        variables:
          - name: PLUGIN_DAEMON_OFF
            type: String
            description: ""
            required: false
            value: "true"

Harness Cloud: You don't need DinD Background steps with Harness Cloud build infrastructure, and you can run GitHub Actions in Action steps instead of Plugin steps.