9. Continuous Integration
More information on Continuous Integration (CI) coming soon!
METplus utilizes GitHub Actions to run processes automatically when changes are pushed to GitHub. These tasks include:
Building documentation
Building a Docker image to run tests
Creating/Updating Docker data volumes with new input data used for tests
Running unit tests
Running use cases
Comparing use case output to truth data
Creating/Updating Docker data volumes with truth data to use in comparisons
9.1. Workflow Control
GitHub Actions is controlled by a file in the .github/workflow directory called testing.yml. If this file exists and is valid (no errors), GitHub Actions will read this file and trigger a workflow run if the triggering criteria is met. It can run multiple jobs in parallel or serially depending on dependency rules that can be set. Each job can run a series of commands or scripts called steps. Job steps can include “actions” with can be used to perform tasks. Many useful actions are provided by GitHub and external collaborators. Developers can also write their own custom actions to perform complex tasks to simplify a workflow.
9.1.1. Name
The name of a workflow can be specified to describe an overview of what is run. Currently METplus only has 1 workflow, but others can be added. The following line in the testing.yml file:
name: METplus CI/CD Workflow
defines the workflow that runs all of the jobs.
9.1.2. Event Control
The “on” keyword is used to determine which events will trigger the workflow to run:
on:
push:
branches:
- develop
- develop-ref
- feature_*
- main_*
- bugfix_*
pull_request:
types: [opened, reopened, synchronize]
This configuration tells GitHub Actions to trigger the workflow when:
A push event occurs on the develop or develop-ref branch
A push event occurs on a branch that starts with feature_, main_, or bugfix_
A pull request is opened, reopened, or synchronized (when new changes are pushed to the source branch of the pull request.
9.1.3. Jobs
The “jobs” keyword is used to define the jobs that are run in the workflow. Each item under “jobs” is a string that defines the ID of the job. This value can be referenced within the workflow as needed.
9.2. Job Control
9.2.1. Default Behavior
9.2.1.1. On Push
When a push to a feature_*, bugfix_*, main_v*, or develop* branch occurs the default behavior is to run the following:
Build documentation
Update Docker image
Look for new input data
Run unit tests
Run any new use cases
9.2.1.2. On Pull Request
When a pull request is created into the develop branch or a main_v* branch, additional jobs are run in automation. In addition to the jobs run for a push, the scripts will:
Run all use cases
Compare use case output to truth data
9.2.1.3. On Push to Reference Branch
Branches with a name that ends with “-ref” contain the state of the repository that will generate output that is considered “truth” data. In addition to the jobs run for a normal push, the scripts will:
Run all use cases
Create/Update Docker data volumes that store truth data with the use case output
9.2.2. Commit Message Keywords
The automation logic reads the commit message for the last commit before a push. Keywords in the commit message can override the default behavior. Here is a list of the currently supported keywords and what they control:
ci-skip-all: Don’t run anything - skip all automation jobs
ci-skip-use-cases: Don’t run any use cases
ci-run-all-cases: Run all use cases
ci-run-diff: Obtain truth data and run diffing logic
ci-only-docs: Only run build documentation job - skip the rest