GitHub Actions – A quick example for ANTLR

I am sure there are hundreds of better tutorials for GitHub actions. However, I decided that it would be nice to have tests run on every push to my repository of the code developed for my ANTLR Tutorial Series, and it seemed a good idea to document the process here.

First, what are GitHub Actions? Basically, is code that runs when something happens in your repository. You can define what is the event to trigger that action (you can even trigger the actions manually), and which code to run. The usual triggers are pull requests and merges, but they can be other. The actions vary accordingly with the requirements of the project, but common actions are running tests and creating software releases.

The repository for which I intended to add a GitHub action is here. It is a C# solution, with three projects: one that is a custom build task (named BuildAntlr, responsible for creating the parser code for an ANTLR grammar), the main project (named Logo2SVG, a tool to convert LOGO code into SVG) and a project with the tests for this project (named LogoTests)

The action I want is triggered by a Pull Request or a Commit, and I just want it to build the projects and run the tests. If everything goes smoothly, the action gets a green check mark.

To create a GitHub action, we use the Actions separator. Then, we can create an empty action, or create one based on a template. There are templates for almost anything, and GitHub will detect your project language and suggest some of them. For my project, I searched the .net action, with the description Build and test a .NET or ASP.NET Core project. We then click the Configure button. A code editor will open and show the template:

# This workflow will build a .NET project
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-net

name: .NET

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 6.0.x
    - name: Restore dependencies
      run: dotnet restore
    - name: Build
      run: dotnet build --no-restore
    - name: Test
      run: dotnet test --no-build --verbosity normal

The file has a name, the actions that trigger the actions, and the actions themselves. The on directive specifies that this action will run both on push and pull requests, for the main branch. The action follows the jobs directive. Each job is executed in parallel, so in this situation we want just one action, to build and test the code. In this case, this job specified that it runs on top of the image for ubuntu-latest.

The steps can be specified as a bash command line, or using an action defined in a macro. The first step uses the checkout macro, to clone the repository. Then, we set up the dotnet repository in the Ubuntu image. Follows three different commands for dotnet, to restore their dependencies, build the projects, and test.

For my repository, I need two new steps: to install the Java runtime and download the ANTLR jar file. My edited version of the action follows:

name: .NET

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - name: Install Java
      run: sudo apt-get update -y && apt-get install -y default-jre
    - name: Download and Install Antlr
      run: sudo mkdir -p /opt/local/lib && sudo curl -L "https://www.antlr.org/download/antlr-4.13.1-complete.jar" -o /opt/local/lib/antlr-4.13.1-complete.jar
    - uses: actions/checkout@v3
    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 7.0.x
    - name: Restore dependencies
      run: dotnet restore
    - name: Build AntlrBuild project
      run: dotnet build --no-restore BuildAntlr
    - name: Build
      run: dotnet build --no-restore
    - name: Test
      run: dotnet test --no-build --verbosity normal

The defined steps are:

• Line 15: Installation of the Java runtime, using the apt command line tool. The default-jre installs the default environment defined by the Ubuntu distribution. Note that, before installing it, it is wise to update the package repository.
• Line 17: Downloading the ANTLR jar file and storing it inside the /opt/local/lib folder (that was specified as the default folder on my repository code).
• Follows the standard lines from the template, just replacing the version of the dotnet.
• I added an extra step, line 26, to build the BuildAntlr task, as it is required by the main project build.

I am sure this is not top-notch, and that there are surely better ways of doing this (please feel free to comment for suggestions). Nevertheless, it might be useful for someone. Who knows 😊