GitHub Action Runner Emulation

GitHub Action Runner Emulation is a bundled plugin that runs action commands, emulating a GitHub Action Runner.

In this topic:

Plugin overview

Use the GitHub Action Runner Emulation plugin to run steps of a GitHub Actions job. You can define multiple steps to trigger a sequence of action commands.

The plugin supports actions from the GitHub Marketplace, or you can write and run your own actions.

Running the plugin is equivalent to running a single GitHub Actions job. The plugin can include one or more steps with action commands specified in YAML.

Supported actions

As a technical preview, the plugin can run some but not all GitHub Actions. The following table provides some guidelines on supported actions:

Hosting actions in a local repository

You can run actions directly from GitHub, or actions that are hosted in a local repository on the PulseUno Git server.

You can create a local repository of GitHub actions in the following ways:

• Create a mirror of the GitHub repository and keep it synchronized with the source. For details, see Mirror a Git repository.
• Import the GitHub repository. For details, see Create Git repositories.

Back to top

Prerequisites

The following are the prerequisites for using the plugin:

• Download the Node 20 binaries and extract them in the following location on the appropriate agent:

  <agent-data-directory>/externals/node20

  If the externals directory doesn't exist, create it manually.

  To ensure seamless chain runs, avoid using symbolic links.

• Establish trust as follows, depending on where the actions are hosted:

  Location where actions are hosted	Method to establish trust
  Local PulseUno repository	The PulseUno Git repository where the actions are stored must trust the Git repository containing the chain that runs these actions. For details on how to establish trust, see Define trusted products for Git repository.
  GitHub	Establish trust for the GitHub actions you want to run. For details, see Define trusted GitHub actions.

• Powershell 7.x must be installed.

Back to top

Configure the plugin

When configuring the GitHub Action Runner Emulation plugin, specify one or more actions to run.

To configure the GitHub Action Runner Emulation step:

1. Add the GitHub Action Runner Emulation step to a chain, as described in Create chains.

2. (Optional) Rename the plugin step.

3. Select the mode for specifying actions, and set the action commands:

   Mode	Description
   Action	Use this mode if you want to run a single action. Specify the action command and set its input and environment variables:
   	Action name	Enter the action command using the following syntax: <space>/<git-repo>@<tag-or-sha> where: <space>/<git-repo> specifies the location of the action command in PulseUno. <tag-or-sha> specifies the branch, tag, or commit hash of the action command. As a security measure, we recommend that you use a full-length commit hash to pin the action to a specific commit. For example, to install Java, enter: actions/setup-java@v2
   	Inputs	Set input variables for the action command. Enter each key=value pair on a new line. For example, if you are installing Java, specify the Java distribution and version: distribution=adopt java-version=11 You can define values as global, agent, chain, or built-in variables. For details on how to reference them, see Syntax.
   	Environment	Set environment variables for the action command. Enter each key=value pair on a new line. You can define values as global, agent, chain, or built-in variables. For details on how to reference them, see Syntax.
   Yaml	Enter the YAML definition of the steps to run. Use the GitHub Actions workflow syntax and make sure that the indentation of the YAML code is correct. For example: steps: - name: <action-name> uses: <space>/<git-repo>@<tag-or-sha> inputs: key: 'value' env: key: 'value' where: <action-name> specifies a name for the action. <space>/<git-repo> specifies the location of the action command in PulseUno. <tag-or-sha> specifies the branch, tag, or commit hash of the action command. As a security measure, we recommend that you use a full-length commit hash to pin the action to a specific commit. inputs lists input variables scoped for the action command. env lists environment variables that are scoped for the action command and may be passed to other actions down the sequence. For details about the syntax for input and environment variables, see Syntax. For examples of action commands defined in YAML, see GitHub Actions examples.
   File in workspace	Use a YAML file in the agent's workspace. The file contains a YAML definition of the steps to run. To create the file, use the GitHub Actions workflow syntax, as described in Yaml.

4. (Optional) Set additional options for the plugin:

   Option	Description
   Enable enhanced annotations	This option enables the notice workflow command and allows action commands to generate findings without using a problem matcher. Clear this option to disable the creation of notices.
   Export environment variables set by actions	Select this option if you want the environment variables defined in actions of this chain step to be available to other steps down the chain. For example, when your run an action command to install Java, and you define the Java location as JAVA_HOME, select this option to pass JAVA_HOME to later chain steps.
   Export issue matcher for use by later GitHub actions	If you use a problem matcher to scan actions for issues that match a specified regular expression, by default the problem matcher is available to other GitHub Action Runner Emulation steps down the chain. Clear this option to stop sharing the problem matcher with later chain steps.
   Export paths for use by later GitHub actions	By default, changes to system paths are available to other GitHub Action Runner Emulation steps down the chain. Clear this option if you don't want to pass updated system paths to later chain steps.
   Enable deprecated output commands	By default, the deprecated set-output command is disabled. Instead, you can write the output parameters to the GITHUB_OUTPUT environment file. Select this option to allow the set-output command. Caution: This option is provided to support older actions that haven't been updated. We do not recommend enabling this option as it poses a potential security risk.
   Allow insecure commands such as set-env and add-path	By default, the deprecated commands set-env and add-path are disabled. Instead, you can write the environment variables and system path variables to the GITHUB_ENV and GITHUB_PATH environment files respectively. Select this option to allow the set-env and add-path commands. Caution: This option is provided to support older actions that haven't been updated. We do not recommend enabling this option as it poses a potential security risk.
   Allow unsupported stop command tokens	Select this option to allow the tokens defined by the workflow command stop-commands to be an incorrect value, such as an empty value or an action command. Caution: This option is provided to support older actions that haven't been updated. We do not recommend enabling this option as it poses a potential security risk.
   Delete docker images pulled by the action	If the plugin pulls Docker images when running the action commands, select this option to delete the Docker images after finishing the chain step.
   Enable debug logging	Select this option to include extended information about the action commands in the logs. Debug logging is useful for diagnosing actions but may significantly increase the log size.

5. (Optional) Define the control options for the plugin step:

   • Enable step. By default, the step is enabled to run. Clear this option if you need to deactivate the step.

     Disabled steps are skipped when the chain runs.

   • Fail the step. Specify the conditions for failing the step, such as unit test failures, findings criteria, and/or console log entries.

   • Mark step as unstable. Specify the conditions for making the step unstable, such as unit test failures, findings criteria, and/or console log entries.

6. (Optional) Specify the output variables to be passed to other steps down the chain. For details, see Publish output variables.

Back to top

GitHub Actions environment variables

The plugin supports a set of default GitHub Actions environment variables. You can use global, agent, chain, or built-in variables as values.

If you run your own actions, we recommend using PulseUno environment variables. For details, see Environment variables.

Supported GitHub Actions environment variables

The following default environment variables are supported.

Syntax

Depending on the mode in which you specify action commands, use the following syntax to reference variables:

ENV_VAR_1: 'my value'
ENV_VAR_2: ${{ vars.custom_variable }}
ENV_VAR_3: ${{ pulse.built_in_variable }}

RUNNER_OS: 'Linux'
JAVA_HOME: ${{ vars.java_home }}
GITHUB_SERVER_URL: ${{ pulse.url }}

Back to top

GitHub Actions examples

This section provides examples of action commands defined in YAML.

Example 1: Download and install Java version 8 from Adopt OpenJDK:

steps:
  - name: Install Java
    uses: actions/setup-java@v4
    with:
       distribution: 'adopt'
       java-version: '8'
  - run: java -version

Example 2: To run scripts that use Node 12, download and install Node version 12:

steps:
  - name: Install Node 12
    uses: actions/setup-node@v4 
    with:
       node-version: '12'
  - run: node -v

Back to top

See also:

• Use plugins
• View chain runs