Forge is a library and CLI for running reusable steps from various proprietary CI systems using a pluggable container runtime. This, for example, makes the functionality provided to GitHub Actions easily consumable (or testable) by users of other CI systems.

Forge currently exposes running GitHub Actions (e.g. actions/setup-go), Concourse Resources (e.g. concourse/git-resource) and local Azure DevOps Tasks (e.g. Npm@1).

From a release.

Using brew:

brew install frantjc/tap/forge

From source:

git clone https://github.com/frantjc/forge
cd forge
make

Using go:

go install github.com/frantjc/forge/cmd/forge

In GitHub Actions:

  - uses: frantjc/forge@v0

For GitHub Actions, Forge will try to source the GitHub Actions variables from the working directory's Git configuration as well as GitHub's default environment variables.

forge use actions/setup-go@v3 -w go-version=1.22

Forge mounts the current working directory to the Action's GITHUB_WORKSPACE as well as cache directories respecting the XDG Base Directory Specification to the Action's RUNNER_TOOLCACHE and RUNNER_TEMP.

That is to say, after running the above command, go should be installed to XDG_CACHE_HOME/forge/runner/toolcache.

You can also use local GitHub Actions by starting the reference with "/" or "." to signify that it is an absolute or relative local filepath, respectively.

forge use ./testdata/actions/docker

For additional debugging, you can attach to the container running the Action:

forge use -a ./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.

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

For Concourse Resources, Forge will source resource_types and resources from the working directory's .forge.yml (overridable with -c). This schema is conveniently compatible with Concourse's pipeline schema.

Just like Concourse itself, Forge ships with some Resource Types builtin that can be overridden.

forge get mock -v version=v0.0.0

You can also attach to the container executing the Resource to snoop around:

forge get -a mock -v version=v0.0.0

The Resource's image must have bash or sh on its PATH for the attach to work.

Install forge:

  - uses: frantjc/forge@v0

For Azure DevOps, you can execute local Tasks by starting the reference with "/" or "." to signify that it is an absolute or relative local filepath, respectively. Remote Tasks are not supported at this time as there is no standard protocol for referencing them.

forge task ./testdata/tasks/node

For additional debugging, you can attach to the container running the Task:

forge task -a ./testdata/tasks/node

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

Automation begins with a shell script that executes a bunch of CLI commands often to test, build and publish some code. The next step is to set up some continuous integration (CI) system that executes that script in response to some event such as a commit to a Git repository's main branch. Such CI systems tend to identify that all of the scripts that they are executing do a lot of the same things--checkout a Git repository, setup a tool and so on.

In an effort to make their platform easier to use and to refactor the shared functionality out of all of the aforementioned scripts, CI systems in the past have introduced reusable "plugins"/"Actions"/"Resources"/"Tasks"/"Orbs" which take minimal configuration to do a complex task. GitHub Actions' actions/checkout, for example, takes one short line of code to invoke and accepts a bunch of optional configuration to fulfill many related use cases.

Unfortunately, using such powerful plugins outside of the the system they were built for can be wildly difficult. This makes debugging the use of these plugins require long feedback loops. It also makes migrating from one CI system to another treacherous, having to replace uses of one system's plugins with another's.

Forge aims to remedy this.

• git is required
• make is required
• go 1.20 is required for multi-error handling
• docker is required to test as it is its only runtime
• upx is required for compressing shim
• node 20 is required for developing the action