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

Tooling
,
1

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.

67 Likes
2

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

3

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
4

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

5

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

6

You can add

env:
  JULIA_NUM_THREADS: 2

at the top-level of your YAML file

7 Likes
7

great, thank you, that works

8

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?

2 Likes
9

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

Replace MYPACKAGE with the name of your package.

2 Likes
10

Awesome, thanks for the fix!

1 Like
11

Shouldn’t this also work for pull requests from forks? Any idea why https://github.com/JuliaDiff/DiffResults.jl/pull/20 isn’t triggering GHA CI?

12

Because by default actions cannot trigger other actions, so CompatHelper action doesn’t trigger CI action. You can manually push (or amend) the commit, also closing/reopening the PR might work.

For a more long-term solution set up ab SSH deploy key, see https://github.com/JuliaRegistries/CompatHelper.jl/blob/ccf7ef4c4c36e6f4bd45071e4ae7e721b77b82e6/README.md#12-set-up-the-ssh-deploy-key-optional

4 Likes
13

I read about this change in Travis. However, in all my repository, things are working fine including macOS builds. Should I change to Github actions?

14

Likely because you haven’t finished yet your free credits: Travis CI - Test and Deploy with Confidence

That’s up to you. If you like Travis and are willing to pay for it (or try to apply for free OSS credits, good luck with that) you can stick with it

2 Likes
15

Ah! That’s sad. Thanks for the information. I think I will just remove macOS.

16

All other platforms will drain your free credits, too

1 Like
17

Are there advantages/disadvantages to combining the Documentation workflow with the CI workflow?

18

Since we do not have something like allow-failure as in Travis, how can I make it in GitHub Actions? Create two actions?

19

The documentation of the events and badges for the Github actions is not that clear. What do you guys use for the events for the badges for passing tests, building documentations, and coverage?

20

I am using something like this for passing tests:

[![Build status](https://github.com/JuliaSpace/SatelliteToolbox.jl/workflows/CI/badge.svg)](https://github.com/JuliaSpace/SatelliteToolbox.jl/actions)

And created two actions ci.yml and ci-nightly.yml, because the latter can fail. I did not change the badges for accessing documentation.

3 Likes