GitHub action Java workflows
| Name | Description |
|---|---|
| gh-pages-publish.yaml | Publish API docs to GitHub Pages |
| gh-release.yaml | Create a GitHub Release |
| maven-publish.yaml | Publish an artifact on Maven Central |
| unit-ci.yaml | Build and run Unit tests |
This project uses it's own workflows in order to test them (the Java App/Lib is just a demo/example). Copy and paste one or more of the following files into your project .github/workflows directory and update parameters accordingly:
| Name | Description |
|---|---|
| ci.yaml | Continuous Integration of an App/Lib |
| cd.yaml | Continuous Deployment of an App/Lib with GitHub release |
The ci workflow invokes unit-ci to configure, build, and unit test. The ci workflow can be customized with docker commands to launch containers and run integration tests (Java Example).
The cd workflow invokes gh-release and optionally gh-pages-publish. The gh-release workflow uses the VERSION file to determine which tag to create. The cd workflow generally should monitor the VERSION file for changes to trigger the workflow.
The gh-pages-publish workflow creates docs on GitHub Pages. For example, the demo Lib docs are here: javadoc API docs. The workflow creates a new directory in the gh-pages branch of your project for each release using the semver name and copies the auto generated API docs there. An index HTML with JavaScript can then use the GitHub API to lookup the directories in the branch and list them in the index. This means there is a one-time setup for each project where you need to commit and push the index.html, index.js, and .nojekyll files. The path to the docs are then obtained at https://jeffersonlab.github.io/project/ where project is your project name. Example setup commit - notice first line of index.js must be customized with project name.
The maven-publish workflow publishes to Maven Central and assumes you have an account already setup at central.sontatype.com. You must already have a namespace defined, claimed, and validated, plus a GPG Signing key published and a Maven Central Access Token created. Then, this action requires the following secrets be defined in your project GitHub Action Secrets config:
- MAVEN_CENTRAL_USERNAME: This is actually an access token name (not your personal central username).
- MAVEN_CENTRAL_PASSWORD: This is the access token value
- SIGNING_KEY: This is an ASCII armored GPG Signing Key.
- SIGNING_PASSWORD: This is the password used to protect your signing key
This action relies on the third-party gradle-maven-plublish-plugin.
This project includes a Hello World Java app to demonstrate the workflow. Use the java-devcontainer to configure, build, and test:
gradlew build
Workflows are versioned in semver just as with regular software, however, the GitHub Action workflows convention is to reference a major version number such that backwards compatible minor and patch updates are received automatically. This means a separate major tag such as v1 must be moved after each release. To move a major tag after a release execute (v1 shown):
git tag -f v1
git push --tags -f