A (very) quick introduction to GitHub Actions

Author: Oscar Mojica, Supercomputing Center for Industrial Innovation, Senai Cimatec

In this tutorial we will introduce Github Actions as a tool for lightweight automation of scientific data workflows. While GitHub Actions have become integral to the software development lifecycle, many scientific programmers, especially those not extensively engaged in software deployment, might not be well-acquainted with their features or understand their potential within data pipelines. Using straightforward examples, we aim to showcase how GitHub Actions can be applied to automate various data processing tasks. Our objective is to empower participants to envision and implement their own strategies for integrating GitHub Actions into their work processes.

Prerequisites: GitHub account, basic familiarity with git, Github, and version control, programming in Interpreted/Compiled Programming Languages.

Audience: scientific programmers interested in automating components of their workflows through existing tools for software continuous integration/deployment.

GitHub Actions Introduction

• Intro slides
• Github actions documentation

Setup

• Fork this repo
• Enable Github Actions:
  • Settings -> Actions -> Allow actions and reusable workflows
  • Managing Permissions Documentation

GitHub Actions Python Environment Workflow

First, we will run a basic workflow which creates a python environment with a few scientific packages and prints out their version

• .github/workflows/python_env.yml
• go to Actions tab, click on Python Environment, and click Run workflow: this will manually trigger the workflow (dispatch_workflow)
• click on the newly created run to see the execution progress

Numerical inverse Laplace transform Visualization Workflow

Next, we will demonstrate how GitHub Actions can be used to display an image in a GitHub README generated by the workflow (only if the image changed). In this specific example, a Fortran implementation of the Gaver Stehfest algorithm Stehfest, Harald. "Algorithm 368: Numerical inversion of Laplace transforms [D5]." Communications of the ACM 13.1 (1970): 47-49. is used to determine the inverse Laplace transforms of the function $1/(s+1)$, whose result is $e^{(-t)}$. The last step of the workflow involves plotting the inverse Laplace transform computed numerically and comparing it with the exact result.

• .github/workflows/main.yml

• Here's an overview of the workflow:

  • Triggering the Workflow: The workflow is triggered by the workflow_dispatch event, allowing manual execution.

  • Job Configuration: The workflow defines a job named test that runs on different operating systems (ubuntu-latest and windows-latest). It uses a matrix strategy to vary the operating system and compiler toolchain (GCC, Intel) for testing.

  • Permissions: Permissions are set to allow the default GITHUB_TOKEN to write to the repository's contents.

  • Steps:

    • a. Checkout Code: The code is checked out using the actions/checkout action with submodule support.

    • b. Get Compiler: The Fortran compiler is set up based on the specified compiler and version in the matrix.

    • c. Setup Fortran Package Manager (FPM): FPM is configured using the fortran-lang/setup-fpm action.

    • d. Run NILP App Test: The Fortran compiler version is displayed, and FPM is used to run the NILP app in release mode.

    • e. Get PNG File: This step installs gnuplot on Ubuntu and generates a PNG file using the gnuplot script (nilp.p).

    • f. Commit: A commit is made to the GitHub repository, adding any changed or new PNG files.

    • g. Upload PNG File: PNG files from the png/ directory are uploaded as artifacts named "Graphic."

    • Conditions: The last three steps (get png file, commit, upload png file) are conditional on Ubuntu and GCC in the matrix. They execute only if the operating system is Ubuntu and the compiler is GCC.

After the workflow is executed a nilp.png file is updated in the repo and is visualized below. Please note that the PNG file is updated only when changes are made to the source code, resulting in modifications to the text file used by Gnuplot

⚠️ CI Workflow Failure Notice

Please note that the current Continuous Integration (CI) workflow has encountered issues with two of its six jobs. Specifically, the jobs that run on the macos-latest operating system and use gfortran and intel-classic compilers are failing. This issue has been documented in the open issue #32.

The resolution of this issue is being investigated by the relevant team. In the meantime, please be aware that the remaining jobs in the CI workflow are running successfully. As a result of this, the CI badge at the top of the README will appear red.

Thank you for your understanding while the issue is being addressed.

License

These materials are for a course intended to provide a (very) quick introduction to GitHub Actions. The course is aimed at a scientific audience. Comments, corrections, and additions are welcome.

All source code is made available under the MIT license.

The full text of these licenses is provided in the LICENSE file.