Manual GitHub Actions Workflow in WildFly

GitHub actions workflow is a valuable tool that automates development process and continuous integration. While it’s great to see every pull request can be verified automatically upon submission, sometimes we also like the flexibility to tweak which OS, JDK distribution and version to use, which tests to run, which maven options to specify, or which system properties to apply. Basically, a more customizable build environment and testing plan targeted for a particular issue at hand. This is what a manual workflow is for. This post will walk you through how to do this in WildFly.

Use cases for manual workflow

A pull request in WildFly usually triggers more than 10 CI jobs, and some of them take hours to complete. The Manual workflow in WildFly can greatly reduce the duration and resource consumption via parameterization, and perform the desired verification without the overhead of a full-blown CI cycle. And below are some more occasions where manual workflow is a good fit:

  • The build takes too long on your local machine.

  • You want to reproduce certain failures that only occur in GitHub CI settings, but not on your local machine.

  • You want to build and test WildFly on certain combination of OS and JDK versions not readily available locally.

  • You want to test your WildFly code changes in a clean environment, without the interference fom other projects.

How to start manual workflow

First thing to consider is where to run the manual workflow. It depends on your role and permission within WildFly project. If you are in maintainer role, you can run it in upstream WildFly repository, or your fork of it. Other WildFly contributors and watchers are free to run it in their own fork.

In either case, navigate to the Actions tab of WildFly repository, choose Manual Build and Test from the list of workflows on the left panel, and then click Run workflow dropdown on the right-side panel. The following is a sample screenshot of various configurations available in the dropdown menu:

Manual workflow

Manual workflow parameters

  • Branch: Choose the branch your wish to run against, typically a topic branch containing some new code you want to verify. It defaults to main branch. This is the standard GitHub branch selector with quick filtering.

  • OS: Choose the runner operating system, either ubuntu-latest or windows-latest. It defaults to ubuntu-latest.

  • JDK Distribution: Choose the JDK distribution to build and test WildFly. It defaults to temurin and supports the following distributions. For more information, see setup-java action docs.

    • temurin: Eclipse Temurin

    • semeru: IBM Semeru Runtime Open Edition

    • microsoft: Microsoft Build of OpenJDK

    • oracle: Oracle JDK

    • zulu: Azul Zulu OpenJDK

    • corretto: Amazon Corretto Build of OpenJDK

    • liberica: Liberica JDK

  • jdk-version: Enter JDK version, a string value that is an exact version or a version range using SemVer notation. It’s a required parameter with no default. For more information, see setup-java action docs

  • args: Enter optional, additional maven command options. It defaults to -Dquickly. Some common args are:

    • -Dquickly: activates the quick-build maven profile, which skips steps like testing, javadoc generation and checkstyle, For more information, see its definition in pom.xml

    • -DskipTests: a maven option to skip running tests

    • -DallTests: activates the maven profile that runs all suitable tests

    • other system properties or maven options

  • timeout: Enter number of minutes beyond which the workflow job will time out. It’s an optional parameter and defaults to 120 minutes. How to choose a good timeout value depends largely on the previous parameter, args, which determines which maven profile to activate, which tests to run, or which build steps to execute.