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.


# 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
    branches: [ master ]
    branches: [ master ]

# There is a single job here called "build" (The word "build" is NOT a keyword, you can use anything there)
    # 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
        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
      # 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:
      # Will set up the desired version of perl on the current OS.
      - name: Set up perl
        uses: shogo82148/actions-setup-perl@v1
          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


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.

    -H "Accept: application/vnd.github.v3+json" \ -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