GitHub Actions for Perl Development

You might remember that I’ve been taking an interest in GitHub Actions for the last year or so (I even wrote a book on the subject). And at the Perl Conference in Toronto last summer I gave a talk called “GitHub Actions for Perl Development” (here are the slides and the video).

During that talk, I mentioned a project I was working on to produce a set of reusable workflows that would make it easier for anyone to start using GitHub Actions in their Perl development. Although (as I said in the talk) things were moving pretty quickly on the project at the time, once I got back to London, several other things became more important and work on this project pretty much stalled. But over the last couple of weeks, I’ve returned to this project and I’ve finally got some of the workflows into a state where I’ve been using them successfully in my GitHub repos and I think they’re now ready for you to start using them in yours. There are three workflows that I’d like you to try:

• cpan_test: This runs your test suite and reports on the results
• cpan_coverage: This calculates the coverage of your test suite and reports the results. It also uploads the results to coveralls.io
• cpan_perlcritic: This runs perlcritic over your code and reports on the results

And using these workflows in your GitHub repos is as simple as creating a new file in the .github/workflows directory which contains something like this:

name: CI

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

jobs:
  build:
    uses: PerlToolsTeam/github_workflows/.github/workflows/cpan-test.yml@main

  coverage:
    uses: PerlToolsTeam/github_workflows/.github/workflows/cpan-coverage.yml@main

  perlcritic:
    uses: PerlToolsTeam/github_workflows/.github/workflows/cpan-perlcritic.yml@main

There are a couple of parameters you can use to change the behaviour of these workflows. In the Toronto talk, I introduced the idea of a matrix of tests, where you can test against three operating systems (Linux, MacOS and Windows) and a list of Perl versions. By default, the cpan-test workflow uses all three operating systems and all production versions of Perl from 5.24 to 5.38. But you can change that by using the perl_version and os parameters. For example, if you only wanted to test on Ubuntu, using the most recent two versions of Perl, you could use this:

build:
  uses: PerlToolsTeam/github_workflows/.github/workflows/cpan-test.yml@main
  with:
    perl_version: "['5.36', '5.38']"
    os: "['ubuntu']"

Annoyingly, the parameters to a reusable workflow can only be a single scalar value. That’s why we have to use a JSON-encoded string representing an array of values. Maybe this will get better in the future.

The cpan-perlcritic workflow also has a parameter. You can use level to change the level that perlcritic runs at. The default is 5 (the gentlest level) but if you were feeling particularly masochistic, you could do this:

perlcritic:
    uses: PerlToolsTeam/github_workflows/.github/workflows/cpan-perlcritic.yml@main
    with:
      level: 1

The workflows are, of course, available on GitHub. It would be great to have some people trying them out and reporting back on their experiences. Raising issues and sending pull requests is very much encouraged.

Please let me know how you get on with them.

The post GitHub Actions for Perl Development appeared first on Perl Hacks.

Comments

[Vincent A. Cicirello]

Nice set of workflows. I haven't used Perl in a long time, but I use GitHub Actions for similar purposes for Java. I have a few ideas based on things I do that might be useful for your coverage workflow.

1. It might be useful to use actions/upload-artifact after generating the coverage report to attach the report to the GitHub Actions run. If you want to examine report, you can then download from the Actions tab.

2. I find it useful to comment coverage on PRs. I think there are Actions you can use for that. But I just use the GitHub cli in a step of my workflow. It's available to workflows by default. Useful for other things too, but for commenting on a PR the command is gh pr comment PR-NUMBER -b "Your comment". You can use markdown in the comment string. In some of my Java projects, my workflow comments the coverage percentage and the branches coverage.

[Dave Cross]

Thanks for the suggestions. I definitely have plans for making the results from these workflows easier to see. And artifacts and/or comments will certainly be part of that.