Merge pull request #480 from bstansberry/pullRequest464

Pull request464

_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.