If you create GitHub Actions via GitHub’s UI by going to the URL of the form `https://github.com///actions/new`, it provides templates for setting up the build. However, the template is broken.

There are four problems with the default template

  1. No dependency caching – so package dependencies will be resolved and reinstalled every time
  2. No cancelation of stale executions – If you pushed a commit and before the tests finish, you decide to push another commit then the stale commits are not canceled. Rather they continue executing!
  3. No path filtering – So a change to README will trigger the execution of, for example, linters and tests!
  4. No timeouts – Rogue tests can run forever leading to resource exhaustion

All these are fixable.

  1. Dependency caching is language-specific – see the directions in the actions/cache repository.
  2. Canceling stale executions is easy. Just add 
    concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
  3. Path filtering requires knowing the right dependencies but it is not hard. For example, for a job linting Python files, it will be **.py
  4. A reasonable job-level timeout makes sense. Look at the past execution and put a limit of 2X based on that. For example, if a job takes 5 minutes on average, timeout-minutes: 10 limits the job to 10 minutes.

Let’s consider a simple template that GitHub generates for building Python code and improving it.

# Template generated by GitHub
# This workflow will install Python dependencies, run tests and lint with a single version of Python
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python

name: Python application

on:
  push:
    branches: [ "master" ]
  pull_request:
    branches: [ "master" ]

permissions:
  contents: read

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up Python 3.10
      uses: actions/setup-python@v3
      with:
        python-version: "3.10"
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install flake8 pytest
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
    - name: Lint with flake8
      run: |
        # stop the build if there are Python syntax errors or undefined names
        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
    - name: Test with pytest
      run: |
        pytest

 

My improvements are marked with # Improvement: comments

name: Python application

on:
  push:
    branches: [ "master", "main" ]
    # Improvement #1: Filter on files that should trigger this workflow
    paths:
      - 'requirements.txt'
      - '**.py'
      # Assume that this is the path of this file in the repo
      - '.github/workflows/python-app.yml'
  pull_request:
    branches: [ "master", "main" ]
    # Improvement #1: Filter on files that should trigger this workflow
    paths:
      - 'requirements.txt'
      - '**.py'
      # Assume that this is the path of this file in the repo
      - '.github/workflows/python-app.yml'

permissions:
  contents: read

# Improvement #2: Cancel existing executions when new commits are pushed onto the branch
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # Improvement #3: Rename the job name, this makes it easier to run locally 
  # with a tool like https://github.com/nektos/act
  buildPythonApp:

    runs-on: ubuntu-latest
    # Improvement #4: Add a timeout of 15 mins
    timeout-minutes: 15

    steps:
    - uses: actions/checkout@v3
    - name: Set up Python 3.10
      uses: actions/setup-python@v3
      with:
        python-version: "3.10"
       
    # Improvement #5: Cache Python dependencies using the hash of "requirements.txt" as the key
    # This step must be executed before "pip install" 
    - uses: actions/cache@v3
      with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
        restore-keys: |
          ${{ runner.os }}-pip-
      
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install flake8 pytest
        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
    - name: Lint with flake8
      run: |
        # stop the build if there are Python syntax errors or undefined names
        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
    - name: Test with pytest
      run: |
        pytest

 

Update: after getting a lot of positive feedback. I have open-sourced a project gabo to automate this. Feel free to try it out.