foundry-toolchain Action

This GitHub Action installs Foundry, the blazing fast, portable and modular toolkit for Ethereum application development.

Example workflow

name: CI

permissions: {}

on:
  push:
  pull_request:
  workflow_dispatch:

env:
  FOUNDRY_PROFILE: ci

jobs:
  check:
    name: Foundry project
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false
          submodules: recursive

      - name: Install Foundry
        uses: foundry-rs/foundry-toolchain@v1

      - name: Show Forge version
        run: forge --version

      - name: Run Forge fmt
        run: forge fmt --check

      - name: Run Forge build
        run: forge build --sizes

      - name: Run Forge tests
        run: forge test -vvv

Inputs

Name	Required	Default	Description	Type
version	No	stable	Version to install, e.g. stable, rc, nightly or any SemVer version with or without v prefix (e.g. v1.5.0 or 1.5.0)	string
network	No	ethereum	Network version to install, e.g. ethereum, tempo.	string
cache	No	true	Whether to cache Foundry data or not.	bool
cache-key	No	${{ github.job }}-${{ github.ref }}-${{ github.sha }}	The cache key to use for caching.	string
cache-restore-keys	No	[${{ github.job }}-${{ github.ref }}-, ${{ github.job }}-refs/heads/${{ github.base_ref }}- (PRs only), ${{ github.job }}- (legacy fallback)]	The cache keys to use for restoring the cache.	string[]

Caching

By default, this action matches Forge's behavior and caches all RPC responses, Etherscan queries, and other data in the ~/.foundry/cache directory. This is done to speed up the tests and avoid hitting the rate limit of your RPC provider.

The default logic of the caching is as follows:

• Always load the latest valid cache for the current ref (for example, the same branch or the same PR merge ref), and always create a new one with the updated cache.
• On pull requests, if there is no cache for the PR ref yet, fall back to the latest cache for the base branch.
• If neither scoped cache exists yet, fall back once more to the legacy job-wide prefix so older caches remain usable during migration.
• When there are no changes to the fork tests, the cache does not change but the key does, since the key is based on the commit hash.
• When the fork tests are changed, both the cache and the key are updated.

Scoping the default restore keys to github.ref, with an explicit github.base_ref fallback for pull requests, avoids a PR restoring the newest cache from an unrelated ref that happens to share the same job prefix while still letting the first PR run warm from the base branch cache. The final ${{ github.job }}- fallback is kept only for backward compatibility with older caches and is intentionally lower priority because it can match caches from unrelated refs. If you intentionally want to share caches across different refs, pass broader cache-restore-keys explicitly.

If you would like to disable the caching (e.g. because you want to implement your own caching mechanism), you can set the cache input to false, like this:

- name: Install Foundry
  uses: foundry-rs/foundry-toolchain@v1
  with:
    cache: false

Custom Cache Keys

You have the ability to define custom cache keys by utilizing the cache-key and cache-restore-keys inputs. This feature is particularly beneficial when you aim to tailor the cache-sharing strategy across multiple jobs. It is important to ensure that the cache-key is unique for each execution to prevent conflicts and guarantee successful cache saving.

For instance, if you wish to utilize a shared cache between two distinct jobs, the following configuration can be applied:

- name: Install Foundry
  uses: foundry-rs/foundry-toolchain@v1
  with:
    cache-key: custom-seed-test-${{ github.sha }}
    cache-restore-keys: |-
      custom-seed-test-
      custom-seed-
---
- name: Install Foundry
  uses: foundry-rs/foundry-toolchain@v1
  with:
    cache-key: custom-seed-coverage-${{ github.sha }}
    cache-restore-keys: |-
      custom-seed-coverage-
      custom-seed-

Deleting Caches

You can delete caches via the GitHub Actions user interface. Just go to your repo's "Actions" page:

https://github.com/<OWNER>/<REPO>/actions/caches

Then, locate the "Management" section, and click on "Caches". You will see a list of all of your current caches, which you can delete by clicking on the trash icon.

For more detail on how to delete caches, read GitHub's docs on managing caches.

Fuzzing

Note that if you are fuzzing in your fork tests, the cache strategy above will not work unless you set a fuzz seed. You might also want to reduce your number of RPC calls by using Multicall.

Summaries

You can add the output of Forge and Cast commands to GitHub step summaries. The summaries support GitHub flavored Markdown.

For example, to add the output of forge snapshot to a summary, you would change the snapshot step to:

- name: Run snapshot
  run: NO_COLOR=1 forge snapshot >> $GITHUB_STEP_SUMMARY

See the official GitHub docs for more information.

Building

When opening a PR, you must build the action exactly following the below steps for CI to pass:

Install nvm.

$ nvm install
$ nvm use
$ npm ci --ignore-scripts
$ npm run typecheck
$ npm run build

You must use the Node.js version 24.13.0 to build.