GitHub Actions tutorial

GitHub Actions is a popular solution for automating CI/CD. If you are getting started with GitHub Actions, in this article, we will guide you through the core concepts of the platform and provide a step-by-step guide to setting Liberica Native Image Kit with a special Github Action, which will serve as an example of integrating the platform into your every-day life.

What is GitHub Actions: key concepts

GitHub Actions is a platform that allows for build, test, and deployment automation within a GitHub repository. The core concept of GitHub Actions is a workflow, which is a set of one or more jobs triggered when a specific event in a repository occurs (for example, a pull request or a commit).

Each job is executed within its own virtual machine called runner and is divided into several steps. A step executes a defined command, script, or an action, which is a standalone reusable set of commands (it is also called extension). Actions perform complex tasks and help developers to minimize repetitive work. You can create your own action or browse the GitHub Marketplace for a ready one. Find more information about utilizing actions in the How to use GitHub Actions section below.

Workflows are defined in a YAML file. This file includes the description of the trigger events, scripts that need to be run, the environment, and any other necessary information.The YAML files describing workflows are stored in the .github/workflows directory in the project.

GitHub Actions is not the only automation platform. But there are features distinguishing it from other CI/CD tools. You can read more about them in our previous article.

How to use GitHub Actions

You can specify your own workflow by creating a .github/workflows repository in your project and putting there a file with the .yml or .yaml extension (let’s name it demo.yml, for example) with a similar content:

name: Java Tests

on:
  pull_request:

jobs:
  build:
    uses: some-custom-scriptl@v1

Here, you define the name of the workflow, the trigger event (on: pull_request) and a job that executes the exact version of your script, in this case, version 1 (uses: some-custom-scriptl@v1). When you commit and push these changes, they will be automatically installed in your GutHub repository and run every time you create a pull request.

However, as we already mentioned, you can browse a wide selection of ready actions and integrate the ones you require into your project. For instance, there’s a Setup Java action to download and install a required version of a Java runtime (you can choose Liberica JDK as a distribution). There is now also an action for setting up GraalVM (including Liberica Native Image Kit), which we discuss in more details below.

GitHub Action for GraalVM

GraalVM is a Java Virtual Machine and a Java Development Kit written in Java. It aims to increase the performance of JVM-based applications and enables the developers to introduce various programming languages to their project. One powerful feature of GraalVM is Native Image technology that converts Java applications into fully-compiled native executables Ahead-of-time, guaranteeing almost instant startup. To learn more about the platform, refer to our previous article A guide to GraalVM.

A GutHub Action for GraalVM enables you to install various distributions of GraalVM:

• Oracle GraalVM,
• GraalVM Community Edition (CE),
• Enterprise Edition (EE),
• Mandrel,
• Liberica Native Image Kit,

As well as necessary GraalVM components:

• Native Image,
• GraalVM components (e.g., Truffle languages).

The action performs the following steps among others: it downloads required packages, exports a $GRAALVM_HOME environment variable, and adds $GRAALVM_HOME/bin to $PATH.

How to set up Liberica Native Image Kit with a GitHub Action

Liberica Native Image Kit (NIK) is a GraalVM CE-based Native Image compiler used by default in Spring Boot buildpacks for generating native images. As opposed to GraalVM CE that offers only SerialGC, Liberica NIK integrates ParallelGC allowing for significant latency reduction. Liberica NIK also supports JavaFX for converting desktop applications into native executables.

Starting with version 1.2.0, the setup-graalvm action supports Liberica Native Image Kit. Below is the YAML file for using it:

name: Native AOT build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: graalvm/setup-[email protected]
        with:
          distribution: 'liberica'
          java-version: '21'
          java-package: 'jdk+fx'
      - name: Show paths
        run: |
          echo "GRAALVM_HOME: $GRAALVM_HOME"
          echo "JAVA_HOME: $JAVA_HOME"
          java --version
          native-image --version
      - name: Build native image
        run: native-image -jar ...

Let’s look more closely at the configuration:

• distribution: Use 'liberica' for Liberica NIK
• java-version: Use the exact JDK version number such as '21.0.2' or just '21'
• java-package: Use 'jdk+fx' to build a JavaFX based app. Otherwise, you can simply omit this input or use 'jdk', which is the default package.

The action described in the file above sets up JAVA_HOME and GRAALVM_HOME environment variables:

$ echo "GRAALVM_HOME: $GRAALVM_HOME"
GRAALVM_HOME: /opt/hostedtoolcache/bellsoft-liberica-vm-linux-amd64/21.0.2/x64/bellsoft-liberica-vm-openjdk21-23.1.2

$ echo "JAVA_HOME: $JAVA_HOME"
JAVA_HOME: /opt/hostedtoolcache/bellsoft-liberica-vm-linux-amd64/21.0.2/x64/bellsoft-liberica-vm-openjdk21-23.1.2

It also adds them to the PATH environment variable:

$  java --version
openjdk 21.0.2 2024-01-16 LTS
OpenJDK Runtime Environment Liberica-NIK-23.1.2-1 (build 21.0.2+14-LTS)
OpenJDK 64-Bit Server VM Liberica-NIK-23.1.2-1 (build 21.0.2+14-LTS, mixed mode, sharing)

$  native-image --version
native-image 21.0.2 2024-01-16
GraalVM Runtime Environment Liberica-NIK-23.1.2-1 (build 21.0.2+14-LTS)
Substrate VM Liberica-NIK-23.1.2-1 (build 21.0.2+14-LTS, serial gc)

Now you can proceed with building a native image for your app:

$ native-image -jar app.jar ...

GitHub Actions Summary

To sum up, GitHub Actions makes working with GtHub even more convenient. You can write your own workflows or implement the existing actions that describe complex tasks, thus eliminating the necessity of writing a lot of additional code and accelerating CI/CD.