From 210884f6452a24c1cfc783830eca9d2bcddcdc72 Mon Sep 17 00:00:00 2001 From: Sven Strittmatter Date: Fri, 21 Jul 2023 22:04:42 +0200 Subject: [PATCH 1/9] #35 First parts of documentation for release ceremony Signed-off-by: Sven Strittmatter --- release.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 release.md diff --git a/release.md b/release.md new file mode 100644 index 00000000..661d1f3d --- /dev/null +++ b/release.md @@ -0,0 +1,70 @@ +# Release Documentation + +Here we describe all the ceremonial stuff necessary to publish a Java library to Maven Central. + +## GPG Guide for Maven Release Signing + +This guide is based on [Working with PGP Signatures](https://central.sonatype.org/publish/requirements/gpg/) and [OpenPGP Best Practices](https://riseup.net/ru/security/message-security/openpgp/gpg-best-practices). + +### About our key + +Real name: `the secureCodeBox authors` +Email: `securecodebox@iteratec.com` +Comment: `Maven Release Signing Key` +Fingerprint: `40AA7D29EB6DE0667D7E723ADE4725604A739BAF` +Password: [see our password manager] + +### Create a new key + +We create a new GPG key with: + +```shell +gpg --full-generate-key +``` + +### Import the private key + +Download private key from 1Password and import it locally + +```shell +gpg --import private.key +``` + +### Export the Private Key + +#### For GitHub Actions + +```shell +gpg --armor --export-secret-keys 40AA7D29EB6DE0667D7E723ADE4725604A739BAF +``` + +#### For 1Password + +```shell +gpg -o private.key --export-secret-key 40AA7D29EB6DE0667D7E723ADE4725604A739BAF +``` + +### Expiration + +It is recommended to use an expiration date less than two years. We use an interval of **two years**. This means that we need to extend the expiration date every two years! + +#### How to extend the expiration date? + +1. Download the private key file `private.key` from 1Password +2. Import it locally: `gpg --import private.key` +3. Select the key : `gpg --edit-key 40AA7D29EB6DE0667D7E723ADE4725604A739BAF` +4. Now select the subkey and set the expire date (use `2y` for two years): +```shell +gpg> key 1 +gpg> expire +``` +5. Save it: +```shell +gpg> save +``` +6. Update the private key in out password manager and GitHub Secrets + +## TODOs + +- How to remember the expirationd date over time & with changing developers? +- Do we need to import the public key in sonatype? From eb72b85626b351cc5b6dd7bd969a5a53cdf6416d Mon Sep 17 00:00:00 2001 From: Heiko Kiesel Date: Mon, 24 Jul 2023 16:16:20 +0200 Subject: [PATCH 2/9] Add Credentials description Signed-off-by: Heiko Kiesel --- release.md | 45 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/release.md b/release.md index 661d1f3d..f0f72074 100644 --- a/release.md +++ b/release.md @@ -2,7 +2,33 @@ Here we describe all the ceremonial stuff necessary to publish a Java library to Maven Central. -## GPG Guide for Maven Release Signing + +## Credentials + +Publishing to Maven Central requires authentication in the form of a username-password or an User Token (as username and password). +We use User Tokens [2] for authentication, which are stored in our password manager. + +### Local (on device) + +The `MAVEN_USERNAME` and `MAVEN_PASSWORD` environment variable needs to be set on the device. + +### GitHub Actions + +In the GitHub Secrets [1], we need to add two secrets called `MAVEN_USERNAME` and `MAVEN_PASSWORD` (Github enforces a leading `SECRET_TOKEN`). +They can be accessed in a yaml file with `${{ secrets.MAVEN_USERNAME }}` and `${{ secrets.MAVEN_PASSWORD }}`. +We pass both these secrets in the `env` block. + +For example: + +```yaml +- name: Publish to Maven Central + run: ./gradlew publish + env: + MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }} + MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }} +``` + +## GPG Guide for Maven Signing This guide is based on [Working with PGP Signatures](https://central.sonatype.org/publish/requirements/gpg/) and [OpenPGP Best Practices](https://riseup.net/ru/security/message-security/openpgp/gpg-best-practices). @@ -24,7 +50,7 @@ gpg --full-generate-key ### Import the private key -Download private key from 1Password and import it locally +Download private key from password manager and import it locally ```shell gpg --import private.key @@ -38,7 +64,7 @@ gpg --import private.key gpg --armor --export-secret-keys 40AA7D29EB6DE0667D7E723ADE4725604A739BAF ``` -#### For 1Password +#### For Password Manager ```shell gpg -o private.key --export-secret-key 40AA7D29EB6DE0667D7E723ADE4725604A739BAF @@ -46,14 +72,17 @@ gpg -o private.key --export-secret-key 40AA7D29EB6DE0667D7E723ADE4725604A739BAF ### Expiration -It is recommended to use an expiration date less than two years. We use an interval of **two years**. This means that we need to extend the expiration date every two years! +It is recommended to use an expiration date less than two years. +We use an interval of **two years**. +This means that we need to extend the expiration date every two years! +To remember, we added an appointment to the team calendar. #### How to extend the expiration date? -1. Download the private key file `private.key` from 1Password +1. Download the private key file `private.key` from password manager 2. Import it locally: `gpg --import private.key` 3. Select the key : `gpg --edit-key 40AA7D29EB6DE0667D7E723ADE4725604A739BAF` -4. Now select the subkey and set the expire date (use `2y` for two years): +4. Now select the Subkey and set the expire date (use `2y` for two years): ```shell gpg> key 1 gpg> expire @@ -66,5 +95,7 @@ gpg> save ## TODOs -- How to remember the expirationd date over time & with changing developers? - Do we need to import the public key in sonatype? + +[1]: https://www.theserverside.com/blog/Coffee-Talk-Java-News-Stories-and-Opinions/GitHub-Actions-Secrets-Example-Token-Tutorial +[2]: https://help.sonatype.com/iqserver/managing/user-management/user-tokens From 722fb7b4b4ebe582b9fe3a56232a659ecd90714e Mon Sep 17 00:00:00 2001 From: Heiko Kiesel Date: Tue, 25 Jul 2023 15:50:28 +0200 Subject: [PATCH 3/9] Add explanation on how to add signing key and password to github actions Signed-off-by: Heiko Kiesel --- release.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/release.md b/release.md index f0f72074..c6eb3cb7 100644 --- a/release.md +++ b/release.md @@ -64,6 +64,22 @@ gpg --import private.key gpg --armor --export-secret-keys 40AA7D29EB6DE0667D7E723ADE4725604A739BAF ``` +In the GitHub Secrets [1], add the output of this command to the `SIGNING_KEY` secret. +Additionally, you must add the corresponding password in as `SIGNING_PASSWORD`. +Both can be accessed in a yaml file with `${{ secrets.SIGNING_KEY }}` and `${{ secrets.SIGNING_PASSWORD }}`. +We pass both these secrets in the `env` block- + +For example: + +```yaml +- name: Publish to Maven Central + run: ./gradlew publish + env: + SIGNING_KEY: ${{ secrets.SIGNING_KEY }} + SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }} + ... +``` + #### For Password Manager ```shell From 1143bca4d062f814790e696d2283138bf948383e Mon Sep 17 00:00:00 2001 From: Heiko Kiesel Date: Tue, 25 Jul 2023 16:10:43 +0200 Subject: [PATCH 4/9] Enforce tests before publishing Signed-off-by: Heiko Kiesel --- build.gradle | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/build.gradle b/build.gradle index 6b79c704..f87ad9af 100644 --- a/build.gradle +++ b/build.gradle @@ -116,6 +116,11 @@ jacocoTestReport { dependsOn test // tests are required to run before generating the report } +// Enforce running tests before publishing +tasks.withType(PublishToMavenRepository).configureEach {task -> + task.dependsOn test +} + // https://docs.gradle.org/current/userguide/signing_plugin.html signing { if (!version.endsWith('SNAPSHOT')) { // only sign non-snapshot versions From f998a360bc184560bf3c40ad4270167850390998 Mon Sep 17 00:00:00 2001 From: Heiko Kiesel Date: Tue, 25 Jul 2023 16:18:00 +0200 Subject: [PATCH 5/9] Delete test workflow as the test task is always required before publishing Signed-off-by: Heiko Kiesel --- .github/workflows/test.yml | 26 -------------------------- 1 file changed, 26 deletions(-) delete mode 100644 .github/workflows/test.yml diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml deleted file mode 100644 index 5157e2e7..00000000 --- a/.github/workflows/test.yml +++ /dev/null @@ -1,26 +0,0 @@ -# SPDX-FileCopyrightText: 2023 iteratec GmbH -# -# SPDX-License-Identifier: Apache-2.0 - -# This workflow will test a Java project with Gradle -# For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-gradle - -name: Java Tests -on: push - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: Set up JDK 17 - uses: actions/setup-java@v3 - with: - java-version: 17 - distribution: adopt - - name: Validate Gradle wrapper - uses: gradle/wrapper-validation-action@v1.1.0 - - name: Setup Gradle - uses: gradle/gradle-build-action@v2.7.0 - - name: Build with Gradle - run: ./gradlew build From 21afe67c501ca1441ade329965b39d1cf824c879 Mon Sep 17 00:00:00 2001 From: Sven Strittmatter Date: Wed, 26 Jul 2023 11:41:08 +0200 Subject: [PATCH 6/9] #35 Do not hard code volatile key id in docs Signed-off-by: Sven Strittmatter --- release.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/release.md b/release.md index c6eb3cb7..b5c85512 100644 --- a/release.md +++ b/release.md @@ -61,7 +61,7 @@ gpg --import private.key #### For GitHub Actions ```shell -gpg --armor --export-secret-keys 40AA7D29EB6DE0667D7E723ADE4725604A739BAF +gpg --armor --export-secret-keys $KEYID ``` In the GitHub Secrets [1], add the output of this command to the `SIGNING_KEY` secret. @@ -83,7 +83,7 @@ For example: #### For Password Manager ```shell -gpg -o private.key --export-secret-key 40AA7D29EB6DE0667D7E723ADE4725604A739BAF +gpg -o private.key --export-secret-key $KEYID ``` ### Expiration @@ -97,8 +97,8 @@ To remember, we added an appointment to the team calendar. 1. Download the private key file `private.key` from password manager 2. Import it locally: `gpg --import private.key` -3. Select the key : `gpg --edit-key 40AA7D29EB6DE0667D7E723ADE4725604A739BAF` -4. Now select the Subkey and set the expire date (use `2y` for two years): +3. Select the key : `gpg --edit-key $KEYID` +4. Now select the subkey and set the expire date (use `2y` for two years): ```shell gpg> key 1 gpg> expire From 106982a291ad547651fa5e3238bea55705a757fa Mon Sep 17 00:00:00 2001 From: Sven Strittmatter Date: Wed, 26 Jul 2023 11:41:35 +0200 Subject: [PATCH 7/9] #35 Remove done todos Signed-off-by: Sven Strittmatter --- release.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/release.md b/release.md index b5c85512..c6a8b6a7 100644 --- a/release.md +++ b/release.md @@ -88,10 +88,7 @@ gpg -o private.key --export-secret-key $KEYID ### Expiration -It is recommended to use an expiration date less than two years. -We use an interval of **two years**. -This means that we need to extend the expiration date every two years! -To remember, we added an appointment to the team calendar. +It is recommended to use an expiration date less than two years. We use an interval of **two years**. This means that we need to extend the expiration date every two years! We use an appointment of the secureCodeBox team calendar which to remind us. #### How to extend the expiration date? @@ -109,9 +106,5 @@ gpg> save ``` 6. Update the private key in out password manager and GitHub Secrets -## TODOs - -- Do we need to import the public key in sonatype? - [1]: https://www.theserverside.com/blog/Coffee-Talk-Java-News-Stories-and-Opinions/GitHub-Actions-Secrets-Example-Token-Tutorial [2]: https://help.sonatype.com/iqserver/managing/user-management/user-tokens From cd764c13be8610301c6172d2ffbf4d201d2e0559 Mon Sep 17 00:00:00 2001 From: Sven Strittmatter Date: Wed, 26 Jul 2023 11:58:39 +0200 Subject: [PATCH 8/9] #35 Refine the release documentation Signed-off-by: Sven Strittmatter --- release.md | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/release.md b/release.md index c6a8b6a7..0063ccb6 100644 --- a/release.md +++ b/release.md @@ -2,11 +2,9 @@ Here we describe all the ceremonial stuff necessary to publish a Java library to Maven Central. - ## Credentials -Publishing to Maven Central requires authentication in the form of a username-password or an User Token (as username and password). -We use User Tokens [2] for authentication, which are stored in our password manager. +Publishing to Maven Central requires authentication in the form of username and password or user token (as username and password). We use [user tokens][user-token] for authentication, which are stored in our password manager. ### Local (on device) @@ -14,9 +12,7 @@ The `MAVEN_USERNAME` and `MAVEN_PASSWORD` environment variable needs to be set o ### GitHub Actions -In the GitHub Secrets [1], we need to add two secrets called `MAVEN_USERNAME` and `MAVEN_PASSWORD` (Github enforces a leading `SECRET_TOKEN`). -They can be accessed in a yaml file with `${{ secrets.MAVEN_USERNAME }}` and `${{ secrets.MAVEN_PASSWORD }}`. -We pass both these secrets in the `env` block. +In the [GitHub Secrets][gh-secrets], we need to add two secrets called `MAVEN_USERNAME` and `MAVEN_PASSWORD`. They can be accessed in a yaml file with `${{ secrets.MAVEN_USERNAME }}` and `${{ secrets.MAVEN_PASSWORD }}`. We pass both these secrets in the `env` block. For example: @@ -30,7 +26,7 @@ For example: ## GPG Guide for Maven Signing -This guide is based on [Working with PGP Signatures](https://central.sonatype.org/publish/requirements/gpg/) and [OpenPGP Best Practices](https://riseup.net/ru/security/message-security/openpgp/gpg-best-practices). +This guide is based on [Working with PGP Signatures][pgp-signatures] and [OpenPGP Best Practices][pgp-best-practices]. ### About our key @@ -50,7 +46,7 @@ gpg --full-generate-key ### Import the private key -Download private key from password manager and import it locally +Download private key from password manager and import it locally: ```shell gpg --import private.key @@ -64,10 +60,8 @@ gpg --import private.key gpg --armor --export-secret-keys $KEYID ``` -In the GitHub Secrets [1], add the output of this command to the `SIGNING_KEY` secret. -Additionally, you must add the corresponding password in as `SIGNING_PASSWORD`. -Both can be accessed in a yaml file with `${{ secrets.SIGNING_KEY }}` and `${{ secrets.SIGNING_PASSWORD }}`. -We pass both these secrets in the `env` block- +In the [GitHub Secrets][gh-secrets], add the output of this command to the `SIGNING_KEY` secret. +Additionally, you must add the corresponding password as `SIGNING_PASSWORD`. Both can be accessed in a YAML file with `${{ secrets.SIGNING_KEY }}` and `${{ secrets.SIGNING_PASSWORD }}`. We pass both these secrets in the `env` block. For example: @@ -77,7 +71,6 @@ For example: env: SIGNING_KEY: ${{ secrets.SIGNING_KEY }} SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }} - ... ``` #### For Password Manager @@ -88,14 +81,14 @@ gpg -o private.key --export-secret-key $KEYID ### Expiration -It is recommended to use an expiration date less than two years. We use an interval of **two years**. This means that we need to extend the expiration date every two years! We use an appointment of the secureCodeBox team calendar which to remind us. +It is recommended to use an expiration date less than two years. We use an interval of **two years**. This means that we need to extend the expiration date every two years! We use an appointment of the secureCodeBox team calendar to remind us. #### How to extend the expiration date? 1. Download the private key file `private.key` from password manager 2. Import it locally: `gpg --import private.key` 3. Select the key : `gpg --edit-key $KEYID` -4. Now select the subkey and set the expire date (use `2y` for two years): +4. Now select the subkey and set the expiry date (use `2y` for two years): ```shell gpg> key 1 gpg> expire @@ -106,5 +99,7 @@ gpg> save ``` 6. Update the private key in out password manager and GitHub Secrets -[1]: https://www.theserverside.com/blog/Coffee-Talk-Java-News-Stories-and-Opinions/GitHub-Actions-Secrets-Example-Token-Tutorial -[2]: https://help.sonatype.com/iqserver/managing/user-management/user-tokens +[gh-secrets]: https://www.theserverside.com/blog/Coffee-Talk-Java-News-Stories-and-Opinions/GitHub-Actions-Secrets-Example-Token-Tutorial +[user-token]: https://help.sonatype.com/iqserver/managing/user-management/user-tokens +[pgp-signatures]: https://central.sonatype.org/publish/requirements/gpg/ +[pgp-best-practices]: https://riseup.net/ru/security/message-security/openpgp/gpg-best-practices From 169418a11c00e7a060042036d0a24b67068aba1a Mon Sep 17 00:00:00 2001 From: Sven Strittmatter Date: Wed, 26 Jul 2023 11:59:20 +0200 Subject: [PATCH 9/9] #35 Move into docs folder bc we will add screenshots to the docs Signed-off-by: Sven Strittmatter --- release.md => docs/release.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename release.md => docs/release.md (100%) diff --git a/release.md b/docs/release.md similarity index 100% rename from release.md rename to docs/release.md