Skip to content

Commit cca3299

Browse files
TartanLeGrandTartanLeGrand
committed
feat: enhance README with detailed reusable workflow documentation
1 parent 65a01d1 commit cca3299

File tree

1 file changed

+92
-59
lines changed

1 file changed

+92
-59
lines changed

‎java-build/README.md‎

Lines changed: 92 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,95 @@
1-
# Java Build and Test
2-
3-
A reusable GitHub Actions workflow for building and testing Java applications with Gradle or Maven.
4-
5-
## Inputs
6-
7-
### `java-version`
8-
9-
**Optional** The Java version to use. Default: `'17'`.
10-
11-
### `java-distribution`
12-
13-
**Optional** The Java distribution to use (temurin, zulu, adopt, etc.). Default: `'temurin'`.
14-
15-
### `build-tool`
16-
17-
**Optional** The build tool to use (gradle or maven). Default: `'gradle'`.
18-
19-
### `gradle-version`
20-
21-
**Optional** The Gradle version to use (only applicable if build-tool is gradle). Default: `'wrapper'` (uses the Gradle Wrapper).
22-
23-
### `gradle-build-task`
24-
25-
**Optional** The Gradle build task to run. Default: `'build'`.
26-
27-
### `gradle-build-file`
28-
29-
**Optional** The Gradle build file to use. Default: `''` (uses the default build.gradle file).
30-
31-
### `maven-version`
32-
33-
**Optional** The Maven version to use (only applicable if build-tool is maven). Default: `'3.9.5'`.
34-
35-
### `maven-goals`
36-
37-
**Optional** The Maven goals to run. Default: `'clean package'`.
38-
39-
### `maven-args`
40-
41-
**Optional** Additional Maven arguments. Default: `''`.
42-
43-
### `working-directory`
44-
45-
**Optional** The working directory where the build commands will be run. Default: `'.'`.
46-
47-
### `upload-artifacts`
48-
49-
**Optional** Whether to upload build artifacts. Default: `true`.
50-
51-
### `artifacts-name`
52-
53-
**Optional** The name of the artifacts to upload. Default: `'build-artifacts'`.
54-
55-
### `artifacts-path`
56-
57-
**Optional** The path to the artifacts to upload (relative to working-directory). Default: `''` (automatically determined based on build tool).
58-
59-
## Example usage
1+
# Java Build and Test - Reusable Workflow Documentation 🚀
2+
3+
## Overview 🌟
4+
5+
This reusable GitHub Actions workflow automates the process of building and testing Java applications. It supports both Gradle and Maven build tools and is highly configurable via inputs. The workflow performs the following actions:
6+
7+
- **Checks Out Your Repository**: Retrieves your code. 📥
8+
- **Sets Up Java JDK**: Installs the specified Java version and distribution. ☕
9+
- **Sets Up Gradle/Maven**: Configures the specified build tool with the desired version. 🔧
10+
- **Builds Your Application**: Compiles and packages your Java application. 🔨
11+
- **Uploads Build Artifacts**: Optionally uploads the build artifacts for later use. 📦
12+
13+
## Workflow Inputs 🛠️
14+
15+
| **Input** | **Description** | **Required** | **Default** |
16+
|-----------------------|--------------------------------------------------------------------|--------------|-------------------|
17+
| **java-version** | Java version to use. | No | `17` |
18+
| **java-distribution** | Java distribution to use (temurin, zulu, adopt, etc.). | No | `temurin` |
19+
| **build-tool** | Build tool to use (gradle or maven). | No | `gradle` |
20+
| **gradle-version** | Gradle version to use (only applicable if build-tool is gradle). | No | `wrapper` |
21+
| **gradle-build-task** | Gradle build task to run. | No | `build` |
22+
| **gradle-build-file** | Gradle build file to use. | No | `''` (empty string) |
23+
| **maven-version** | Maven version to use (only applicable if build-tool is maven). | No | `3.9.5` |
24+
| **maven-goals** | Maven goals to run. | No | `clean package` |
25+
| **maven-args** | Additional Maven arguments. | No | `''` (empty string) |
26+
| **working-directory** | Working directory where the build commands will be run. | No | `.` |
27+
| **upload-artifacts** | Whether to upload build artifacts. | No | `true` |
28+
| **artifacts-name** | Name of the artifacts to upload. | No | `build-artifacts` |
29+
| **artifacts-path** | Path to the artifacts to upload (relative to working-directory). | No | `''` (auto-determined) |
30+
31+
## Job and Steps ⚙️
32+
33+
### Job Name: `build`
34+
35+
- **Runs On**: `ubuntu-latest`.
36+
- **Steps**:
37+
- **Checkout Repository**: Uses `actions/checkout@v4` to fetch your code. 📥
38+
- **Set up JDK**: Configures Java with `actions/setup-java@v4`. ☕
39+
- **Setup Gradle**: If using Gradle, sets up the specified Gradle version. 🔧
40+
- **Build with Gradle**: If using Gradle, runs the specified build task. 🔨
41+
- **Setup Maven**: If using Maven, sets up the specified Maven version. 🔧
42+
- **Build with Maven**: If using Maven, runs the specified goals with arguments. 🔨
43+
- **Set default artifacts path**: Determines the default artifacts path based on the build tool. 📁
44+
- **Upload build artifacts**: If enabled, uploads the build artifacts. 📦
45+
46+
## How to Use This Reusable Workflow 🔄
47+
48+
1. **Save the Workflow File**
49+
This workflow is already saved as `.github/workflows/java-build.yml` in the repository. 💾
50+
51+
2. **Call the Reusable Workflow**
52+
In another workflow file, invoke this reusable workflow like so:
53+
54+
```yaml
55+
name: Build My Java Application
56+
on:
57+
push:
58+
branches: [main]
59+
60+
jobs:
61+
build:
62+
uses: iExecBlockchainComputing/github-actions-workflows/.github/workflows/[email protected]
63+
with:
64+
java-version: '17'
65+
build-tool: 'gradle'
66+
gradle-build-task: 'build'
67+
```
68+
69+
## Workflow Steps in Detail 🔍
70+
71+
1. **Checkout Repository**:
72+
- Uses `actions/checkout@v4` to fetch your code.
73+
74+
2. **Set up JDK**:
75+
- Uses `actions/setup-java@v4` to install and configure the specified Java version and distribution.
76+
- Sets the architecture to x64.
77+
78+
3. **Gradle Build** (if build-tool is 'gradle'):
79+
- Sets up Gradle using `gradle/actions/[email protected]`.
80+
- Runs the specified Gradle build task, using a custom build file if provided.
81+
82+
4. **Maven Build** (if build-tool is 'maven'):
83+
- Sets up Maven using `stCarolas/setup-maven@v5`.
84+
- Runs the specified Maven goals with any additional arguments.
85+
86+
5. **Artifact Handling**:
87+
- If no explicit artifacts path is provided, determines the default path based on the build tool:
88+
- For Gradle: `build/libs`
89+
- For Maven: `target`
90+
- If artifact uploading is enabled, uploads the build artifacts using `actions/upload-artifact@v4`.
91+
92+
## Example Usage Scenarios 📋
6093

6194
### Basic usage with Gradle (default)
6295

0 commit comments

Comments
 (0)