Github Actions is a great product for continuous integration built directly into Github. I primarily use it to run unit tests automatically. However, getting it setup properly has been a challenge. This is an evolving set of notes on how to get it to work consistently.
Github actions are specified in a YAML file in any repository under the path .github/workflows
.
Choosing When To Run an Action
The first part of an action specifies when it runs. This is usually through the adverb on
. The following code is used to do a common pattern that is surprisingly difficult: Run the action on push or pull request but not both.
on:
push:
pull_request:
branches:
# Branches from forks have the form 'user:branch-name' so we only run
# this job on pull_request events for branches that look like fork
# branches. Without this we would end up running this job twice for non
# forked PRs, once for the push and then once for opening the PR.
- '**:**'
Specifying Jobs
Jobs are the meat of the action. Often, you, need to checkout the repository, install any dependencies and run tests. Optionally, you can do a deployment step, but I haven't done much of that yet.
Below is an example that installs python and poetry, a dependency management system for python. I also cache the folder ~/.cache/pypoetry/virtualenvs
, which is the location poetry stores any dependencies. The cache is refreshed anytime poetry's lock file poetry.lock
changes. Once the dependencies are installed, I use pytest to run the unit tests.
jobs:
#Run pytest
test:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v2
- name: Install python
uses: actions/setup-python@v2
with:
python-version: '3.7'
- name: Install poetry
uses: Gr1N/setup-poetry@v4
- name: Cache poetry dependencies
uses: actions/cache@v2
with:
path: ~/.cache/pypoetry/virtualenvs
key: ${{ runner.os }}-poetry-${{ hashFiles('poetry.lock') }}
restore-keys: |
${{ runner.os }}-poetry-
- name: Install dependencies
run: poetry install -E experiments
- name: Run pytest
run: poetry run pytest --doctest-modules
For a full example in context, see here