DOCSEARCHbyAlgolia
Submit Docs

GitHub Actions Runner

repository·main·Indexed 27 days ago

https://github.com/actions/runner

The core application that executes jobs defined in GitHub Actions workflows. It supports both GitHub-hosted environments and self-hosted infrastructure on Windows, macOS, and Linux. Documentation covers self-hosted runner setup, proxy configuration, problem matcher registration, shell execution options, and workflow expression properties like step outcome and conclusion.

Tokens
18.8K
Snippets
38
Records
100
Agent score
91%

What's inside actions-runner

  1. Overview of GitHub Actions Runner

    main
    The GitHub Actions Runner is the application responsible for executing jobs from a GitHub Actions workflow. Runners are used by GitHub Actions in hosted virtual environments, or they can be self-hosted in your own environment to provide custom compute resources for your workflows.

  3. Understand Composite Action Encapsulation

    main
    In GitHub Actions, a composite action is treated as a single, encapsulated logical job step from the perspective of the workflow author. This means the internal implementation details of the composite action (such as specific shell configurations or working directories) are hidden from the consumer. The workflow author interacts with the composite action as one unit, and the action's internal settings should not be directly influenced by the workflow's shell or working-directory settings.

  4. Capabilities and Support for Container Hooks

    main

    The implementation of container hooks provides the following capabilities:

    • Non-Docker Scenarios: Support for non-Docker scenarios on self-hosted runners, allowing customers to customize their Docker invocations.
    • Troubleshooting: Telemetry is included to assist in troubleshooting support issues related to hooks.

  5. Quickstart: Run a job from a real repository

    main

    To build the runner from source and execute actions from a real GitHub repository, follow these steps. You will need your repository URL and a runner registration token (found at https://github.com/{your-repo}/settings/actions/runners/new).

    Note: To ensure your job runs on this custom runner, set runs-on: self-hosted in your workflow file.

    git clone https://github.com/actions/runner
cd runner/src
./dev.(sh/cmd) layout # the runner that built from source is in {root}/_layout
cd ../_layout
./config.(sh/cmd) --url https://github.com/{your-repo} --token ABCABCABCABCABCABCABCABCABCAB # accept default name, labels and work folder
./run.(sh/cmd)

  6. Install the Actions Runner on macOS (x64 or arm64)

    main

    To install the runner on macOS, create a directory, download the appropriate .tar.gz package, and extract it using tar. Replace <RUNNER_VERSION> with your target version.

    # Create a folder
mkdir actions-runner && cd actions-runner
# Download the latest runner package
curl -O -L https://github.com/actions/runner/releases/download/v<RUNNER_VERSION>/actions-runner-osx-x64-<RUNNER_VERSION>.tar.gz
# Extract the installer
tar xzf ./actions-runner-osx-x64-<RUNNER_VERSION>.tar.gz

  8. Create a Composite Action

    main

    A composite action allows you to bundle multiple run steps into a single action. To define one, create an action.yml file and set runs.using to "composite". You then define a steps list containing individual run commands.

    Supported top-level attributes:

    • name
    • description
    • inputs
    • runs
    • outputs

    Supported run step attributes:

    • name
    • id
    • run
    • env
    • shell (Required)
    • working-directory (Optional)
    runs:
  using: "composite"
  steps:
    - run: pip install -r requirements.txt
      shell: bash
    - run: npm install
      shell: bash

  9. Register and unregister problem matchers using workflow commands

    main

    You can register or remove problem matchers during a GitHub Actions job using special workflow commands. This allows for ad hoc or conditional registration of matchers for specific tools.

    Register a matcher: Use the ::add-matcher:: command followed by the path to your problem matcher configuration JSON file.

    Unregister a matcher: Use the ::remove-matcher:: command followed by the owner name of the matcher you wish to remove.

    Note: If you register a matcher with an owner name that is already in use, it will overwrite (clobber) the existing instance.

    ::add-matcher::path-to-problem-matcher-config.json
::remove-matcher::owner

  10. Required Development Dependencies

    main

    To develop and build the runner, ensure you have the following installed:

    • Git: Git for Windows or Linux (required for dev.sh script).
    • cURL: Required for external sh scripts.
    • Visual Studio:
      • Windows: Visual Studio 2017 or newer.
      • Windows ARM: Visual Studio 2022 17.3 Preview or later.

  11. Install the Actions Runner on Linux (x64, arm64, or arm)

    main

    To install the runner on Linux, create a directory, download the appropriate .tar.gz package, and extract it using tar. Replace <RUNNER_VERSION> with your target version.

    # Create a folder
mkdir actions-runner && cd actions-runner
# Download the latest runner package
curl -O -L https://github.com/actions/runner/releases/download/v<RUNNER_VERSION>/actions-runner-linux-x64-<RUNNER_VERSION>.tar.gz
# Extract the installer
tar xzf ./actions-runner-linux-x64-<RUNNER_VERSION>.tar.gz

  12. Debug the Runner Listener

    main

    The Runner.Listener process receives jobs queued on your repository (provided they match the runner's labels, e.g., runs-on: self-hosted). You can launch this process using the Run [build] or Run configurations found in .vscode/launch.json.

    Note that when the listener receives a job, it starts a separate Runner.Worker process. Because this is a different process, you cannot debug the worker using the same debugger session used for the listener; you must start a parallel debugging session.

    {
    "name": "Run [build]",
    "type": "coreclr",
    "request": "launch",
    "preLaunchTask": "build runner layout",  // use the config called "Run" to launch without rebuild
    "program": "${workspaceFolder}/_layout/bin/Runner.Listener",
    "args": [
        "run" // run without args to print usage
    ],
    "cwd": "${workspaceFolder}/src",
    "console": "integratedTerminal",
    "requireExactSource": false,
}