haskell-actions/setup

This action sets up a Haskell environment for use in actions by:

• if requested, installing a version of ghc and cabal and adding them to PATH,
• if requested, installing a version of Stack and adding it to the PATH,
• outputting of ghc-version/exe/path, cabal-version/exe/path, stack-version/exe/path, stack-root and cabal-store (for the requested components).

The GitHub runners come with pre-installed versions of GHC and Cabal. Those will be used whenever possible. For all other versions, this action utilizes ppa:hvr/ghc, ghcup, and chocolatey.

Usage

See action.yml

Minimal

on: [push]
name: build
jobs:
  runhaskell:
    name: Hello World
    runs-on: ubuntu-latest # or macOS-latest, or windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: haskell-actions/setup@v2
      - run: runhaskell Hello.hs

Basic

on: [push]
name: build
jobs:
  runhaskell:
    name: Hello World
    runs-on: ubuntu-latest # or macOS-latest, or windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: haskell-actions/setup@v2
        with:
          ghc-version: '8.8' # Resolves to the latest point release of GHC 8.8
          cabal-version: '3.0.0.0' # Exact version of Cabal
      - run: runhaskell Hello.hs

Basic with Stack

on: [push]
name: build
jobs:
  runhaskell:
    name: Hello World
    runs-on: ubuntu-latest # or macOS-latest, or windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: haskell-actions/setup@v2
        with:
          ghc-version: '8.8.4' # Exact version of ghc to use
          # cabal-version: 'latest'. Omitted, but defaults to 'latest'
          enable-stack: true
          stack-version: 'latest'
      - run: runhaskell Hello.hs

Matrix Testing

on: [push]
name: build
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        ghc: ['8.6.5', '8.8.4']
        cabal: ['2.4.1.0', '3.0.0.0']
        os: [ubuntu-latest, macOS-latest, windows-latest]
        exclude:
          # GHC 8.8+ only works with cabal v3+
          - ghc: 8.8.4
            cabal: 2.4.1.0
    name: Haskell GHC ${{ matrix.ghc }} sample
    steps:
      - uses: actions/checkout@v4
      - name: Setup Haskell
        uses: haskell-actions/setup@v2
        with:
          ghc-version: ${{ matrix.ghc }}
          cabal-version: ${{ matrix.cabal }}
      - run: runhaskell Hello.hs

Multiple GHC versions

If you need multiple versions of GHC installed at the same time, it is possible to run the action twice.

- uses: haskell-actions/setup@v2
  with:
    ghc-version: '9.8.2'

- uses: haskell-actions/setup@v2
  with:
    ghc-version: '8.10.7'

Model cabal workflow with caching

name: build
on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

# INFO: The following configuration block ensures that only one build runs per branch,
# which may be desirable for projects with a costly build process.
# Remove this block from the CI workflow to let each CI job run to completion.
concurrency:
  group: build-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:
    name: GHC ${{ matrix.ghc-version }} on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest]
        ghc-version: ['9.8', '9.6', '9.4', '9.2', '9.0']

        include:
          - os: windows-latest
            ghc-version: '9.8'
          - os: macos-latest
            ghc-version: '9.8'

    steps:
      - uses: actions/checkout@v4

      - name: Set up GHC ${{ matrix.ghc-version }}
        uses: haskell-actions/setup@v2
        id: setup
        with:
          ghc-version: ${{ matrix.ghc-version }}
          # Defaults, added for clarity:
          cabal-version: 'latest'
          cabal-update: true

      - name: Configure the build
        run: |
          cabal configure --enable-tests --enable-benchmarks --disable-documentation
          cabal build all --dry-run
        # The last step generates dist-newstyle/cache/plan.json for the cache key.

      - name: Restore cached dependencies
        uses: actions/cache/restore@v4
        id: cache
        env:
          key: ${{ runner.os }}-ghc-${{ steps.setup.outputs.ghc-version }}-cabal-${{ steps.setup.outputs.cabal-version }}
        with:
          path: ${{ steps.setup.outputs.cabal-store }}
          key: ${{ env.key }}-plan-${{ hashFiles('**/plan.json') }}
          restore-keys: ${{ env.key }}-

      - name: Install dependencies
        # If we had an exact cache hit, the dependencies will be up to date.
        if: steps.cache.outputs.cache-hit != 'true'
        run: cabal build all --only-dependencies

      # Cache dependencies already here, so that we do not have to rebuild them should the subsequent steps fail.
      - name: Save cached dependencies
        uses: actions/cache/save@v4
        # If we had an exact cache hit, trying to save the cache would error because of key clash.
        if: steps.cache.outputs.cache-hit != 'true'
        with:
          path: ${{ steps.setup.outputs.cabal-store }}
          key: ${{ steps.cache.outputs.cache-primary-key }}

      - name: Build
        run: cabal build all

      - name: Run tests
        run: cabal test all

      - name: Check cabal file
        run: cabal check

      - name: Build documentation
        run: cabal haddock all

Inputs

Name	Description	Type	Default
ghc-version	GHC version to use, e.g. 9.2 or 9.2.5.	string	latest
cabal-version	Cabal version to use, e.g. 3.6.	string	latest
stack-version	Stack version to use, e.g. latest. Stack will only be installed if enable-stack is set.	string	latest
enable-stack	If set, will setup Stack.	"boolean"	false/unset
stack-no-global	If set, enable-stack must be set. Prevents installing GHC and Cabal globally.	"boolean"	false/unset
stack-setup-ghc	If set, enable-stack must be set. Runs stack setup to install the specified GHC. (Note: setting this does not imply stack-no-global.)	"boolean"	false/unset
disable-matcher	If set, disables match messages from GHC as GitHub CI annotations.	"boolean"	false/unset
cabal-update	If set to false, skip cabal update step.	boolean	true
ghcup-release-channel	If set, add a release channel to ghcup.	URL	none

Note: "boolean" types are set/unset, not true/false. That is, setting any "boolean" to a value other than the empty string ("") will be considered true/set. However, to avoid confusion and for forward compatibility, it is still recommended to only use value true to set a "boolean" flag.

In contrast, a proper boolean input like cabal-update only accepts values true and false.

Outputs

The action outputs parameters for the components it installed. E.g. if ghc-version: 8.10 is requested, the action will output ghc-version: 8.10.7 if installation succeeded, and ghc-exe and ghc-path will be set accordingly. (Details on version resolution see next section.)

Name	Description	Type
ghc-version	The resolved version of ghc	string
cabal-version	The resolved version of cabal	string
stack-version	The resolved version of stack	string
ghc-exe	The path of the ghc executable	string
cabal-exe	The path of the cabal executable	string
stack-exe	The path of the stack executable	string
ghc-path	The path of the ghc executable directory	string
cabal-path	The path of the cabal executable directory	string
stack-path	The path of the stack executable directory	string
cabal-store	The path to the cabal store	string
stack-root	The path to the stack root (equal to the STACK_ROOT environment variable if it is set; otherwise an OS-specific default)	string

Version Support

This action is conscious about the tool versions specified in versions.json. This list is replicated (hopefully correctly) below.

Versions specified by the inputs, e.g. ghc-version, are resolved against this list, by taking the first entry from the list if latest is requested, or the first entry that matches exactly, or otherwise the first entry that is a (string-)extension of the requested version extended by a .. E.g., 8.10 will be resolved to 8.10.7, and so will 8.

GHC:

• latest-nightly (requires the resp. ghcup-release-channel, e.g. https://ghc.gitlab.haskell.org/ghcup-metadata/ghcup-nightlies-0.0.7.yaml)
• latest (default)
• 9.12.1 9.12
• 9.10.1 9.10
• 9.8.4 9.8
• 9.8.2
• 9.8.1
• 9.6.6 9.6
• 9.6.5
• 9.6.4
• 9.6.3
• 9.6.2
• 9.6.1
• 9.4.8 9.4
• 9.4.7
• 9.4.6
• 9.4.5
• 9.4.4
• 9.4.3
• 9.4.2
• 9.4.1
• 9.2.8 9.2
• 9.2.7
• 9.2.6
• 9.2.5
• 9.2.4
• 9.2.3
• 9.2.2
• 9.2.1
• 9.0.2 9.0
• 9.0.1
• 8.10.7 8.10
• 8.10.6
• 8.10.5
• 8.10.4
• 8.10.3
• 8.10.2
• 8.10.1
• 8.8.4 8.8
• 8.8.3
• 8.8.2
• 8.8.1
• 8.6.5 8.6
• 8.6.4
• 8.6.3
• 8.6.2
• 8.6.1
• 8.4.4 8.4
• 8.4.3
• 8.4.2
• 8.4.1
• 8.2.2 8.2
• 8.0.2 8.0
• 7.10.3 7.10 (deprecated, not on ubuntu-22.04 or up)

Suggestion: Try to support at least the three latest major versions of GHC.

Cabal:

• head (the cabal-head release of the most recent build of the master branch)
• latest (default, recommended)
• 3.12.1.0 3.12
• 3.10.3.0 3.10
• 3.10.2.1
• 3.10.2.0
• 3.10.1.0
• 3.8.1.0 3.8
• 3.6.2.0 3.6
• 3.6.0.0
• 3.4.1.0 3.4
• 3.4.0.0
• 3.2.0.0 3.2
• 3.0.0.0 3.0
• 2.4.1.0 2.4

Recommendation: Use the latest available version if possible.

Stack: (with enable-stack: true)

• latest (default, recommended)
• 3.1.1 3.1
• 2.15.7 2.15
• 2.15.5
• 2.15.3
• 2.15.1
• 2.13.1 2.13
• 2.11.1 2.11
• 2.9.3 2.9
• 2.9.1
• 2.7.5 2.7
• 2.7.3
• 2.7.1
• 2.5.1 2.5
• 2.3.3 2.3
• 2.3.1
• 2.1.3 2.1
• 2.1.1
• 1.9.3.1 1.9
• 1.9.1.1
• 1.7.1 1.7
• 1.6.5 1.6
• 1.6.3.1
• 1.6.1.1
• 1.5.1 1.5
• 1.5.0
• 1.4.0 1.4
• 1.3.2 1.3
• 1.3.0
• 1.2.0 1.2

Recommendation: Use the latest available version if possible.

Beyond the officially supported listed versions above, you can request any precise version of GHC, Cabal, and Stack. The action will forward the request to the install methods (apt, ghcup, choco), and installation might succeed.

Note however that Chocolatey's version numbers might differ from the official ones, please consult their pages for GHC and Cabal.

License

The scripts and documentation in this project are released under the MIT License.

Contributions

Contributions are welcome! See the Contributor's Guide.