diff --git a/_posts/2023-10-04-github-manual-workflow.adoc b/_posts/2023-10-04-github-manual-workflow.adoc new file mode 100644 index 00000000..d4f4a1e4 --- /dev/null +++ b/_posts/2023-10-04-github-manual-workflow.adoc @@ -0,0 +1,72 @@ +--- +layout: post +title: Manual GitHub Actions Workflow in WildFly +date: 2023-10-04 +tags: wildfly github continuous-integration +synopsis: How to manually run GitHub actions workflow to build and test WildFly +author: chengfang +--- + +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 https://github.com/wildfly/wildfly/actions[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: + +image::manual-github-actions-workflow.png[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 https://github.com/actions/setup-java#supported-distributions[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 https://github.com/actions/setup-java#supported-version-syntax[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 https://github.com/wildfly/wildfly/blob/main/pom.xml#L1340[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. diff --git a/assets/img/news/manual-github-actions-workflow.png b/assets/img/news/manual-github-actions-workflow.png new file mode 100644 index 00000000..11d8c980 Binary files /dev/null and b/assets/img/news/manual-github-actions-workflow.png differ