You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> ℹ️ This workflow automatically 'migrates' all files in your new repository, updating the **gradle project group**, **module name**, **package names**, and **all references** to the repo `<owner>/<name>`.
25
-
>
26
-
> - Head over to **Actions** (1)
27
-
> - on the left-hand side select the topmost workflow '**!! INITIAL: Migrate Repo Template !!**' (2)
28
-
> - click the **Run workflow** button (3)
29
-
> -**fill out** the form & **start** the pipeline (4)(5)
2. Create & provide a PAT (Personal Access Token) for the CI/CD pipeline
24
+
25
+
Three workflows commit and push changes to the repository and therefore require additional permissions. ('migrate-repo-template', 'publish-javadoc', 'gradle-release')
26
+
27
+
The jobs expect a secret by the name `CI_GITHUB_TOKEN` that holds a PAT with _write_ permission for _Content_.
28
+
29
+
To create a new access token, the following steps are required (ref [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)):
30
+
1. If the new repo owner is an organisation, **enrol** the organisation for '**Fine-grained personal access tokens**'. In the organisation ['Settings > Third-party Access > Personal access tokens'](https://github.com/organizations/%REPO_OWNER%/settings/personal-access-tokens).
31
+
2. Head to the [Developer settings](https://github.com/settings/tokens?type=beta) and **enrol** your personal account for the new '**Fine-grained personal access tokens**'. (That's a one-off for your account and you might already have done this before)
32
+
3. Next, click on the button '**Generate new token**' and create a token for the target _**Resource owner**_, with access to your project and the following '**Repository Permissions**'
33
+
***Contents:****Read** and **Write** access to code
3. Trigger the '**!! INITIAL: Migrate Repo Template !!**' workflow
44
+
45
+
ℹ️ This workflow automatically 'migrates' all files in your new repository, updating the **gradle project group**, **module name**, **package names**, and **all references** to the repo `<owner>/<name>`.
46
+
47
+
- Head over to **Actions** (1)
48
+
- on the left-hand side select the topmost workflow '**!! INITIAL: Migrate Repo Template !!**' (2)
49
+
- click the **Run workflow** button (3)
50
+
-**fill out** the form & **start** the pipeline (4)(5)
The project template consists of three toplevel _folders_:
43
-
*`.github/`: Defines the Github Actions CI tasks and templates for new pull requests, issues, etc.
63
+
The project template consists of three top-level _folders_:
64
+
*`.github/`: Defines the GitHub Actions CI tasks and templates for new pull requests, issues, etc.
44
65
*`gradle/`: Contains Gradle Configuration files such as the Gradle [Version Catalog](https://docs.gradle.org/current/userguide/platforms.html) and the Gradle Wrapper.
45
-
*`%ARTIFACT_NAME%/`: The library source code (gradle sub-project).
66
+
*`%ARTIFACT_NAME%/`: The library source code (Gradle sub-project).
46
67
47
68
In addition, following _files_ are worth highlighting:
48
69
*`gradle/libs.versions.toml`: A [conventional file](https://docs.gradle.org/current/userguide/platforms.html#sub:conventional-dependencies-toml) to declare a version catalog.
49
-
*`settings.gradle.kts`: The multi-project Gradle settings file. Here are all sub-projects defined.
70
+
*`settings.gradle.kts`: The multi-project Gradle settings file. Here are all the sub-projects defined.
50
71
*`gradle.properties`: Holds the library version, needed & maintained by the CI/CD pipeline [release process](#release-process).
51
72
*`**/build.gradle.kts`: Gradle build file
52
73
53
74
## CI/CD Pipeline
54
-
The heart of this template is the 'Main GitHub Actions CI/CD Pipeline'.
75
+
The heart of this template is the ['Main GitHub Actions CI/CD Pipeline'](https://github.com/%REPO_OWNER%/%REPO_NAME%/actions/workflows/1.pipeline.yml).
@@ -61,14 +82,14 @@ Based on the context (trigger, ref, input arguments) it meets different use case
61
82
Runs for active PRs - as well as part of all subsequent listed use cases.
62
83
2.**Latest**. 'Check', publish SNAPSHOT version to Maven Central and Javadoc (GitHub Pages).
63
84
Runs on pushes to the main branch.
64
-
3.**Release Process**. 'Check', executes (major|minor|patch) release process via Gradle plugin.
85
+
3.**Release Process**. 'Check', executes (major|minor|patch) release process via the Gradle plugin.
65
86
Manually triggered workflow via GitHub UI/API.
66
87
3.**Library Release**. 'Check', publish RELEASE version to Maven Central and Javadoc (GitHub Pages).
67
88
Runs for pushed tags.
68
89
69
90
## Publish to Maven Central
70
91
### Automated Process
71
-
The maven publish process is fully automated and does not require manual action.
92
+
The Maven publish process is fully automated and does not require manual action.
72
93
- The _main_ branch (per process definition) always is set to the next [SNAPSHOT version](gradle.properties) and is published to the Sonatype snapshot repository with each main CI/CD pipeline run. The pipeline runs e.g. when a PR is merged, but can also be triggered manually.
73
94
- Release deployment happens when a new tag is pushed to GitHub. (Part of the [release process](#release-process))
74
95
@@ -80,8 +101,8 @@ In order to deploy your components to OSSRH with Gradle, you have to meet the [r
80
101
81
102
> ℹ️ The publish process uses [io.github.gradle-nexus.publish-plugin](https://plugins.gradle.org/plugin/io.github.gradle-nexus.publish-plugin) under the hood.
82
103
83
-
The gradle project as well as the CI/CD pipeline is already fully prepared for the publish process.
84
-
The GH actions job [callable.publish-sonatype.yml](.github/workflows/callable.publish-sonatype.yml) requires following Secrets:
104
+
The gradle project as well as the CI/CD pipeline is already fully prepared for the publishing process.
105
+
The GH actions job [callable.publish-sonatype.yml](.github/workflows/callable.publish-sonatype.yml) requires the following Secrets:
@@ -95,7 +116,7 @@ Please define the secrets via your repository settings. ([Settings > Security >
95
116
96
117
## Release Process
97
118
### Creating a Release
98
-
To release a new version via the CI/CD Pipeline, please follow instructions below.
119
+
To release a new version via the CI/CD Pipeline, please follow the instructions below.
99
120
- Navigate to Actions (1)
100
121
-\> Main Pipeline (2)
101
122
- Click 'Run workflow' button (3)
@@ -116,16 +137,7 @@ The new version is automatically published to Maven Central! 🚀
116
137
### Prerequisites: PAT provided as `CI_GITHUB_TOKEN`
117
138
The CI/CD 'gradle-release' job expects a secret by the name `CI_GITHUB_TOKEN` that holds a PAT (Personal Access Token) with permission to push tags as part of the release process.
118
139
119
-
To create a new access token, please head over to the [Developer settings](/settings/tokens?type=beta) and enroll for the new 'Fine-grained personal access tokens'.
120
-
Next, click on the button 'Generate new token' and create a token for the target _Resource owner_, with access to your project and the following 'Repository Permissions'
121
-
***Contents:****Read** and **Write** access to code
122
-
***Metadata:****Read** access to metadata
123
-
124
-
Please refer to the official [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).
125
-
126
-
Provide your new PAT either as an Organisation secret or Repository secret.
0 commit comments