Skip to content

Use GitHub Actions ΒΆ

Forge can be used to run, test and debug GitHub Actions (e.g. actions/setup-go) or to utilize them within other CI systems.

Forge is specifically focused on running individual GitHub Actions (e.g. actions/checkout), not entire GitHub Actions' workflows. For example, Forge is not intended to run a workflow such as:

on: push
jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-go@v5
        with:
          go-version: 1.22

Rather, it is intended to run an Action from within a workflow, like so:

forge use actions/setup-go@v5 --with go-version=1.22

When running an Action, Forge mounts the current working directory to the Action's GITHUB_WORKSPACE as well as directories respecting the XDG Base Directory Specification to the Action's RUNNER_TOOLCACHE and RUNNER_TEMP. So, after the above command is ran, if it succeeds, go should be installed somewhere in XDG_CACHE_HOME/forge/runner/toolcache. This can be found more easily by running:

forge cache toolcache

Some Actions rely heavily on some default variables provided by GitHub. For example, actions/checkout requires on the environment variable GITHUB_REPOSITORY to be set to know which repository it should checkout.

Forge does its best to source such variables from the working directory's Git configuration as well as GitHub's default environment variables in its own environment.

However, in the event that an action errors and reports that a variable that it relies on is not set, it's likely that Forge did not find a value for that variable. For example, actions/checkout errors and reports by saying: "[error] context.repo requires a GITHUB_REPOSITORY environment variable like 'owner/repo'".

In such cases, you can provide the value as an environment variable:

GITHUB_REPOSITORY=frantjc/forge forge use actions/checkout@v4

Authentication to GitHub is provided to Forge in a similar way--through the GITHUB_TOKEN environment variable. The value for the environment variable should be a personal access token and can be injected into the environment more safely via something like ~/.bash_profile like so:

export GITHUB_TOKEN=yourtokenhere

Forge can also execute local GitHub Actions. This helps custom Action developers more quickly and easily test out their actions while developing them locally.

To signify to Forge that a GitHub Action can be found on the filesystem as opposed to in a remote GitHub repository, start the reference with "/" or "." for absolute or relative filepaths, respectively. For example:

forge use ./testdata/actions/docker

Local Actions cannot refer to files outside of the action.yml's directory.

For additional assistance with debugging, you can attach to the container running the Action to snoop around as in this example:

forge use --attach ./testdata/actions/dockerfile

If the Action runs using a custom image, that image must have bash or sh on its PATH for the attach to work.