Easy workflow file for setting up GitHub Actions CI for your Julia package

Travis CI no longer offers unlimited free minutes for public open-source repositories.

However, GitHub Actions continues to offer unlimited free minutes for public open-source repositories.

To set up GitHub Actions CI on your repository, simply create a new file named .github/workflows/ci.yml with the following contents.

When you do so, you should:

  1. Edit the line that looks like '1.3' to reflect the minimum Julia version supported by your package. For example, if your package requires Julia 1.5 or greater, edit that line to look like '1.5'.
  2. Change MYPACKAGE to the name of your package.

Here are the contents of the .github/workflows/ci.yml file:

name: CI
on:
  pull_request:
    branches:
      - master
  push:
    branches:
      - master
    tags: '*'
jobs:
  test:
    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        version:
          - '1.3' # Replace this with the minimum Julia version that your package supports. E.g. if your package requires Julia 1.5 or higher, change this to '1.5'.
          - '1' # Leave this line unchanged. '1' will automatically expand to the latest stable 1.x release of Julia.
          - 'nightly'
        os:
          - ubuntu-latest
        arch:
          - x64
    steps:
      - uses: actions/checkout@v2
      - uses: julia-actions/setup-julia@v1
        with:
          version: ${{ matrix.version }}
          arch: ${{ matrix.arch }}
      - uses: actions/cache@v1
        env:
          cache-name: cache-artifacts
        with:
          path: ~/.julia/artifacts
          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
          restore-keys: |
            ${{ runner.os }}-test-${{ env.cache-name }}-
            ${{ runner.os }}-test-
            ${{ runner.os }}-
      - uses: julia-actions/julia-buildpkg@v1
      - uses: julia-actions/julia-runtest@v1
      - uses: julia-actions/julia-processcoverage@v1
      - uses: codecov/codecov-action@v1
        with:
          file: lcov.info
  docs:
    name: Documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: julia-actions/setup-julia@v1
        with:
          version: '1'
      - run: |
          julia --project=docs -e '
            using Pkg
            Pkg.develop(PackageSpec(path=pwd()))
            Pkg.instantiate()'
      - run: |
          julia --project=docs -e '
            using Documenter: doctest
            using MYPACKAGE
            doctest(MYPACKAGE)' # change MYPACKAGE to the name of your package
      - run: julia --project=docs docs/make.jl
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

I used the excellent PkgTemplates.jl package to generate this file.

Specifically, I used the “A More Complicated Example” example from the
PkgTemplates User Guide.

20 Likes

Having recently set up GH actions for a python project, I’m curious: are you intentionally not using the current version cache@v2?

Where one can read what v2, v1, latest etc means for different actions?

      - uses: actions/checkout@v2
      - uses: julia-actions/setup-julia@v1
1 Like

I would start looking in the release notes/changelog of the respective action, e.g. via its GitHub marketplace entry.

Is there a possibility to have more than one thread per job in GitHub Actions?

You can add

env:
  JULIA_NUM_THREADS: 2

at the top-level of your YAML file

3 Likes

great, thank you, that works

Thanks for the post, this works great. Just one thing though, for the documentation I get:

ERROR: ArgumentError: Package JSON3 not found in current path:
- Run `import Pkg; Pkg.add("JSON3")` to install the JSON3 package.

Stacktrace:
 [1] require(::Module, ::Symbol) at ./loading.jl:893
Error: Process completed with exit code 1.

Is this just something I have to add to my packages environment and it’ll go through?

1 Like

Whoops, I had a typo. I’ve fixed the original post.

Replace MYPACKAGE with the name of your package.

2 Likes

Awesome, thanks for the fix!

1 Like