Github Actions for Perl running on Windows, Mac OSX, and Ubuntu Linux

In order to configure GitHub Actions for a Perl project, all you need is to create a directory called .github/workflows and put a YAML file in it. The name of the file does not matter much, as long as it has the yml extension.

This example was copied from the repostory of Array::Compare by Dave Cross. It was called .github/workflows/perltest.yml there.

Then it was slightly changed and annotated with explanations.

examples/workflows/perltest.yml

# Optional, but good to give a name
name: CI

# This means the workflow will be triggered
#    on push to master branch
#    when a pull request arrives to the master branch. (The source branch does not matter)
#    workflow_dispatch to trigger manually or via API call
on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]
  workflow_dispatch:

# There is a single job here called "build" (The word "build" is NOT a keyword, you can use anything there)
jobs:
  build:
    # This creates two dimensions:
    #   One will be called "os"  with the list of the names of the 3 runners of GitHub Actions
    #   The other indicates version numbers of perl
    # The words "os" and "perl" are free text here, they are like variable names.
    # GitHub Action will run the job on 3x2 = 6 different setups
    strategy:
      matrix:
        os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
        perl: [ '5.30', 'latest' ]

    # Using the value from the matrix above we select the platform (operating system) to run on
    runs-on: ${{ matrix.os }}

    # Just a free-text name to be descriptive
    name: Perl ${{ matrix.perl }} on ${{ matrix.os }}

    # we will have several steps
    steps:
      # check out the current repository to the runner
      # This setp did not get a nice "name"
      - uses: actions/checkout@v2

      # Using the action from this repository: https://github.com/shogo82148/actions-setup-perl/
      # Will set up the desired version of perl on the current OS.
      - name: Set up perl
        uses: shogo82148/actions-setup-perl@v1
        with:
          perl-version: ${{ matrix.perl }}

      # 3 separate commands on the command line of the operating system
      # to display the version of perl - just for possible manual verification
      # Installing the dependencies declared by the module
      # Run prove to execute the tests
      - run: perl -V
      - run: cpanm --installdeps .
      - run: prove -lv t

      # Surprisingly, this does not use the Build.PL script that is used by the module
      # I'd probably write
      # - run: |
      #     perl Build.PL
      #     perl Build
      #     perl Build test
      # but then the tests don't run in verbose mode

workflow_dispatch

If workflow_dispatch is enabled in the GitHub Actions workflow you'll be able to run the workflow manually from GitHub UI or via the REST API.

curl -u USERNAME:PERSONAL_TOKEN -X POST \
    -H "Accept: application/vnd.github.v3+json" \
    https://api.github.com/repos/OWNER/REPO_NAME/actions/workflows/WORKFLOW_FILE_NAME/dispatches -d '{"ref":"BRANCH"}'

• USERNAME - Your GitHub username (In my case it is szabgab, in the case of Dave it is davorg)

• PERSONAL_TOKEN - See Create personal access token

• OWNER - This might be your username, or an organization, this is the first part in the URL path of the reposiotry. In the case we used here it is davorg.

• REPO_NAME - The name of the project reposiotory. In this case it is array-compare.

• WORKFLOW_FILE_NAME - In this case it was perltest.yml (including the extension).

• BRANCH - Can be "master" or "main" or whatever branch-name you have

It will sets GITHUB_EVENT_NAME to be workflow_dispatch

For more details, see workflow_dispatch