Skip to content

View or edit on GitHub

This page is synchronized from doc/Github-Actions.md. Last modified on 2025-12-09 00:30 CET by Trase Admin. Please view or edit the original file there; changes should be reflected here after a midnight build (CET time), or manually triggering it with a GitHub action (link).

GitHub Actions

GitHub Actions is a way to automate tasks. We use it to run automated tests of our code, build documentation, and trigger regular database maintenance operations.

Workflows

At the time of writing we have the following "workflows" in GitHub Actions. They can all be found in the .github/workflows directory:

  • docs.yml: builds various documentation (http://what.deforestationfree.com, http://wtf.deforestationfree.com, etc)
  • dumps_schemas.yml: dump schema from our PostgreSQL database and commit it to the repository
  • lint.yml: checks that our code conforms to certain linting standards such as a code formatting standard
  • test.yml: runs a suite of automated tests for the code
  • permalinks.yml: test that URLs which have been permalinked are still alive

How to add a new GitHub action job

If you want to add a new job to GitHub actions, you have two choices. You can either add the job to an existing workflow or make a new workflow. In order to make this decision you should consider the following:

  • When should the job run? If it should run on a daily or weekly basis, it is a good fir for GitHub Actions. If it should be run on every pull request you might want to add it to the test.yml workflow. If it is something you might want to (additionally) manually trigger as a standalone job, it might make sense to make it its own workflow.
  • In what environment should the job run? If the job needs to run in a Python environment with the full suite of Python dependencies you might consider using test.yml. If the job runs with a minimal subset of Python dependencies, it might make sense to make it its own workflow. If the job needs to run within an AWS environment, you might want to run it on AWS SageMaker.
  • Should the job be synchronous or asynchronous? When a job runs in GitHub actions, it uses up "GitHub actions minutes": if the job is very long-lasting you may consider running it on AWS SageMaker instead.

Once you have decided which existing workflow to use, or that you will make a new one, you will need to create or modify a .yml file in the .github/workflows directory. It is a good idea to do this in the GitHub Web UI, since it has some editing extensions which specifically help you adhere to the GitHub Actions YAML schema. Often you can just make a minor edit, like copying the line above.

Below we will go through the steps of creating a brand new workflow. However, you may also wish to follow this procedure even if you are just adding a new job in an existing workflow, because it is a good way to test a new job.

Creating a new job

The best way to make a new job is, to start with at least, to put it in its own workflow. Check out the guide Quickstart for GitHub Actions. Always develop the new workflow on a separate branch! You might want to make the PR a draft PR too, to prevent the test suite etc. from running. You can grab some boilerplate for installing dependencies etc. from existing workflows in the .github/workflows directory.

Once you are happy with the job you can either keep it its own workflow, or copy it into an existing one and delete the new workflow.