CloudBees action: Run a GitHub Actions workflow

The instructions in this content include using GitHub Actions. Refer to GitHub’s documentation:GitHub Actions: Manually running a workflow for more details.

This page provides an example of how to use the ghactions-run-workflow CloudBees action to integrate a GitHub Actions (GHA) workflow into a CloudBees workflow. It includes details about prerequisites, example workflows, and advanced usage with parameters.

The ghactions-run-workflow CloudBees action allows triggering a remote GitHub Actions workflow from within a CloudBees workflow. This integration enables seamless orchestration between CloudBees and GitHub Actions workflows.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.

Prerequisites

GitHub Actions workflow setup:
- The GitHub Actions workflow must specify the workflow_dispatch trigger type to be invoked via REST API calls.
- Refer to GitHub documentation for details about manually running a workflow.
Github Token Permissions:
- The GitHub token used by the ghactions-run-workflow action must have Actions:read/write permissions for the GitHub repository that owns the workflow.

Example GitHub Actions workflow

The following example demonstrates how to create a GitHub Actions workflow that can be triggered via the workflow_dispatch API mechanism.

GitHub repository setup

Imagine a GitHub repository acme-org/hello-repo containing the following file at .github/workflows/say-hello.yml:

name: hello-workflow

on:
  workflow_dispatch:

jobs:
  say-hello:
    runs-on: ubuntu-latest
    steps:
      - name: say hello
        shell: bash
        run: |
          echo "Hello world"▼

This workflow is triggered when a workflow_dispatch event is sent to the repository. When triggered, the workflow runs the say-hello job on a GitHub-hosted virtual machine, as specified by the runs-on syntax. GitHub provides these ephemeral VMs to execute workflows, provisioning a fresh instance for each job run.

Note on syntax

The runs-on syntax is required for GitHub Actions workflows to define the virtual machine (VM) environment in which the workflow will execute. CloudBees workflows run on Kubernetes clusters and therefore do not use this syntax.

Inputs and parameters for `ghactions-run-workflow`

The ghactions-run-workflow action supports the following inputs:

Input name Data type Required? Description

url

String

The GitHub server URL. If not specified, uses https://api.github.com.

token

String

Yes

The GitHub token.

org-name

String

Yes

The GitHub organization name.

repo-name

String

Yes

The GHA repository name.

branch-name

String

Yes

The GHA branch name.

workflow-name

String

Yes

The GHA workflow name.

The GHA workflow-name is the name attribute defined within the target GHA YAML file.

test-type

String

Specifies the test type for generating a job test report. Supported test types are JUnit (junit), TestNG (testng), MSTest (mstest), ProdPerfect (prodperfect), Jmeter (jmeter), Selenium (selenium), Tosca (tosca), Go (go), Jest (jtest), and Playwright (playwright).

test-result-location

String

Specifies the test report file location. Accepts pattern matching, such as my-dir/*/my-file.

parameters

JSON

Any additional parameters, formatted as JSON data in key/value pairs.

Triggering the GitHub Actions workflow from CloudBees

Once the GitHub Actions workflow is defined, it can be triggered from a CloudBees workflow using the ghactions-run-workflow action.

Example CloudBees workflow

Below is an example of a CloudBees workflow that triggers the GitHub Actions workflow defined above:

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: call-github-workflow
on:
  push: (1)
    branches:
      - "**"

jobs:
  do-work:
    steps:
      - name: run external github workflow
        uses: https://github.com/cloudbees-io/ghactions-run-workflow@v1 (2)
        with:
          token: ${{ secrets.GHA_TOKEN }}
          org-name: acme-org
          repo-name: hello-repo
          branch-name: main
          workflow-name: hello-workflow (3)▼

In this workflow:

1	The CloudBees workflow is triggered on any push event.
2	The `ghactions-run-workflow` action sends a `workflow_dispatch` event to the GitHub Actions workflow using the specified parameters.
3	Logs and execution results from the GitHub Actions workflow are included in the output of the CloudBees step.

Passing parameters to the GitHub Actions workflow

GitHub workflows can be enhanced to accept input parameters. The example below demonstrates how to achieve this:

Enhanced GitHub workflow

name: hello-workflow

on:
  workflow_dispatch:
    inputs:
      caller_message:
        description: 'A message from the caller'
        required: true

jobs:
  say-hello:
    runs-on: ubuntu-latest
    steps:
      - name: say hello
        shell: bash
        run: |
          echo "The caller says: ${{ github.event.inputs.caller_message }}"▼

Updated CloudBees workflow

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: call-github-workflow
on:
  push:
    branches:
      - "**"

jobs:
  do-work:
    steps:
      - name: run external github workflow
        uses: https://github.com/cloudbees-io/ghactions-run-workflow@v1
        with:
          token: ${{ secrets.GHA_TOKEN }}
          org-name: acme-org
          repo-name: hello-repo
          branch-name: main
          workflow-name: hello-workflow
          parameters: '{"caller_message":"you_were_invoked_by_CloudBees"}' (1)▼

1	The `parameters` field in the CloudBees workflow uses JSON to pass values to the GitHub Actions workflow.

Known issues

Parameters with spaces in their values can cause errors.
Improvements are planned to enhance logging and error messages.

Usage example

Below is another usage example for running a GitHub Actions workflow with additional test-related inputs:

jobs:
  run-gha-workflow:
    steps:
      - name: Run GHA workflow
        uses: https://github.com/cloudbees-io/ghactions-run-workflow@v2
        with:
          url: ${{ vars.GITHUB_URL }}
          token: ${{ secrets.GHA_TOKEN }}
          org-name: my_org
          repo-name: my_repo
          branch-name: main
          workflow-name: BUILD_PARAM
          test-type: Junit
          test-result-location: junit-service*
          parameters: '{"ENV_NAME":"TEST"}'▼

Additional Resource

Manually running a workflow (GitHub)

CloudBees action: Run a GitHub Actions workflow

Prerequisites

Example GitHub Actions workflow

GitHub repository setup

Note on syntax

Inputs and parameters for ghactions-run-workflow

Triggering the GitHub Actions workflow from CloudBees

Example CloudBees workflow

Passing parameters to the GitHub Actions workflow

Enhanced GitHub workflow

Updated CloudBees workflow

Known issues

Usage example

Additional Resource

Inputs and parameters for `ghactions-run-workflow`