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 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:
forge use --attach ./testdata/actions/dockerfile
If the Action runs using a custom image, that image must have
bash
orsh
on itsPATH
for the attach to work.