Crate gha_runner

gha-runner runs Github Actions workflows. It supports pluggable backends via the RunnerBackend trait, and provides a LocalDockerBackend implementation that runs workflows using local docker containers. You can also analyze the structure of workflow jobs and modify step execution.

Example

use gha_runner::*;
let images: DockerImageMapping = DockerImageMapping {
    ubuntu_18_04: "ghcr.io/catthehacker/ubuntu:act-18.04".into(),
    ubuntu_20_04: "ghcr.io/catthehacker/ubuntu:act-20.04".into(),
};
let runtime = tokio::runtime::Builder::new_current_thread()
    .enable_all()
    .build()
    .unwrap();
runtime.block_on(async move {
    run_workflow_with_local_backend(
        "Pernosco",
        "github-actions-test",
        "6475d0f048a72996e3bd559cdd3763f53fe3d072",
        ".github/workflows/build.yml",
        "Build+test (stable, ubuntu-18.04)",
        &images,
        LocalDockerOptions::default(),
    ).await;
});

Lower-level API

• Fill out a RunnerContext
• Call Runner::new() to create a Runner
• Call Runner::job_descriptions() to get a list of JobDescriptions and pick a job
• Call Runner::job_runner() to create a JobRunner
• Call JobRunner::container_images() to get a list of Docker container images that will be needed, and create one container per image
• Call JobRunner::run_next_step() repeatedly to run each job step, until next_step_index() >= step_count()

Structs

ContainerId

Index into JobRunner::containers

ContainerImage

A full Docker container image name, e.g ghcr.io/catthehacker/ubuntu:js-18.04

DockerImageMapping

Assigns full docker image names to GHA ‘runs-on’ names

ErrorContext

This describes wha we know about the source of an error.

JobDescription

A description of a job in a workflow.

JobRunner

Runs a specific Job. The simplest way to use this is to repeatedly call run_next_step() until next_step_index() >= step_count().

LocalDockerBackend

Runs a GHA workflow using local Docker containers and the docker CLI.

LocalDockerOptions

Optional parameters for run_workflow_with_local_backend

Runner

Analyzes and runs a specific Github Actions workflow.

RunnerContext

This contains various configuration values needed to run a Github Actions workflow. Most of these values are exposed to actions via standard GHA environment variables.

RunnerError

Errors returned by this crate.

StepIndex

An index into the steps in the workflow YAML. This is not the same thing as Github’s “step number”, which includes invisible steps like job creation and isn’t always numbered consecutively.

Enums

ErrorContextRoot

ErrorContextRoot describes what we were processing when an error occurred.

RunnerErrorKind

Details about an error we encountered.

WorkflowResult

The result of run_workflow_with_local_backend

Traits

RunnerBackend

A backend that can run tasks in containers.

Functions

get_workflow

Either fetches workflow data from the repository (if ‘workflow’ is a relative path) or reads it from a file on the local filesystem with that name. Panics if something goes wrong.

run_workflow_with_local_backend

Run a complete workflow using the local docker backend and DefaultImageMapping. If workflow is an absolute path we read that file to get the workflow data, otherwise it’s a repo-relative path and we fetch the workflow data from the repo. Panics if something goes wrong.

zero_access_token

Returns a Github personal access token that has no rights to access anything. It will work for read-only access to public resources. For anything more you have to supply your own token.

Type Definitions

OutputHandler

A callback that receives stdout or stderr data from a step.