Our Research Software Engineering department is very happy to announce the release of a Repository of GitHub Actions for general use across the University. These are tasks that you can use within your automation workflows on GitHub to make some things easier. They’re all curated by us at the University of Manchester, so you can be assured that we’ll keep them safe to use with your research code. You can use them directly from where we’ve published them, with no explicit installation required.

We are seeking to grow the collection as we understand more of the use cases for reusable components at this level across the University. If you have any suggestions for things we might add, we’d love to hear from you. You can either contact us to talk, or directly file a feature request against the repository (though if you do that, please help us understand what you want by giving a reasonable amount of detail).

What are GitHub Actions workflows and how do I use them?

GitHub Actions workflows are a way of doing automation linked to source code repositories stored on GitHub. They can be triggered by various events, and do tasks like checking whether the code builds, passes simple test cases and follows quality guidelines, and can deploy documentation websites derived from the code. Within those workflows, Actions are pieces of reusable activity that present a simpler interface to an underlying task.

They are a powerful tool for making your code better, but, as with any such tool, care should be taken when using them to ensure that the code you run is code that you can trust.

The Actions

We’ve quite a range of Actions that you can use.

check-copyrights

Ensures that all files in your repository have an "acceptable" copyright notice near their top (you tell the action what acceptable means for you; it’s there to help enforce the rules you select).

commit-id

Helps generate a file containing the ID of the commit within it. This is useful for helping you to track what version of your software is in use.

compare-output

Compares the output of a program to a string. Great for simple automatic testing!

configure-nuget-for-github

Sets up NuGet to access private GitHub packages in the .NET ecosystem.

docker-publish-to-ghcr

Publishes a workflow-local Docker image to the GitHub container registry.

download does

Cached downloads of files from the web, for when you have a dependency that doesn’t quite fit the normal patterns.

doxygen-to-pages

Runs the Doxygen documentation generation tool to generate a simple deployable documentation site from your C or C++ code.

instantiate-file

Creates a file with a value provided by your workflow.

python-import-all-test

Runs a simple test to import all the Python files beneath a particular module.

run-c-style-check

Runs a simple style checker against your C or C++ code.

run-clang-tidy

Does static analysis of C or C++ codebases with clang-tidy to find likely problems.

run-pylint

Runs the Python code style checker pylint over some code. This includes support for spell-checking documentation strings, which we’ve found ever so helpful.

todo

Finds FIXME and TODO comments in code, and makes them much easier to address.

Example of Use: Simple Python Checks

Often, it might be common to use several of these together. For example, you might check your Python code for problems with a workflow like this (which you might put in the file .github/workflows/check.yml in your repository):

# On every pushed commit to Github 
on: push 
jobs: 
  check: 
    runs-on: ubuntu-latest 
    steps: 
      # Get the code ready for the rest of the workflow 
      # This one is supplied by GitHub themselves. 
      - uses: actions/checkout@v4 
      # Check for suspected incompleteness markers in comments 
      - uses: UoMResearchIT/actions/todo@v1.0 
      # Check if there’s a consistent import order 
      - uses: UoMResearchIT/actions/python-import-all-test@v1.0 
        with: 
          module: mymodule 
      # Check for common issues and spelling errors in docstrings 
      - uses: UoMResearchIT/actions/run-pylint@v1.0 
        with: 
          package: mymodule 
          language: en_GB 
          dictionary: mydictionary.txt

Some of the above steps are not so simple to implement yourself, especially the running of a spelling check, which has many nuances.

Overall, this makes it so that every time you push a commit, GitHub will annotate that commit with whether this workflow passes. That in turn checks for TODO comments, for basic correctness of the Python code, and for whether a basic set of standard style checks pass (including a spelling check; a custom dictionary is supported for those terms that aren’t in a conventional dictionary, such as many project names).

This is just a simple example; far more complex arrangements of tasks are possible, though the more complex they become, the more they encode bespoke ways of working. Actions are foundational components, but definitely not the whole story.

More Information

For more information, please contact Research Software Engineering, or just check the documentation in the GitHub repository. If you have ideas for further actions, or want to report a problem, your feedback and suggestions are particularly welcome!

Acknowledgements

These reusable actions include work from many research projects over the past decade. In particular, we want to acknowledge the Human Brain Project, the NERC Digital Solutions Hub, the GiFT project, and the LightForm project for their support that have made these possible, both while the actions were developed and while they were intensively tested.