This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/logging-parent.git
The following commit(s) were added to refs/heads/main by this push:
new 8e309e7 Use workflows on the same branch (#379)
8e309e7 is described below
commit 8e309e7e7f7db492c70db592a46cc9482aed2069
Author: Piotr P. Karwasz <[email protected]>
AuthorDate: Mon May 19 21:55:50 2025 +0200
Use workflows on the same branch (#379)
* Use workflows on the same branch
Since most of the PRs to `logging-parent` modify the workflows, we should
not run the reusable workflows from the `@main` branch, but from the same
branch as the PR.
This PR changes all non-reusable workflows to use the
`./.github/workflows/<workflow>` syntax, which uses the workflow file from the
same branch as the calling workflow.
* fix: add examples of workflow usage
---
.github/workflows/build.yaml | 6 +-
.github/workflows/deploy-site.yaml | 6 +-
.github/workflows/merge-dependabot.yaml | 4 +-
.../site/antora/modules/ROOT/examples}/build.yaml | 65 ++++++----
.../antora/modules/ROOT/examples}/deploy-site.yaml | 57 ++++-----
src/site/antora/modules/ROOT/pages/features.adoc | 27 +---
src/site/antora/modules/ROOT/pages/usage.adoc | 4 +-
src/site/antora/modules/ROOT/pages/workflows.adoc | 142 +++++++++++++++++++++
8 files changed, 221 insertions(+), 90 deletions(-)
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
index f7a0a46..124759a 100644
--- a/.github/workflows/build.yaml
+++ b/.github/workflows/build.yaml
@@ -44,14 +44,14 @@ jobs:
build:
if: github.actor != 'dependabot[bot]'
- uses: apache/logging-parent/.github/workflows/build-reusable.yaml@main
+ uses: ./.github/workflows/build-reusable.yaml
with:
site-enabled: true
deploy-snapshot:
needs: build
if: github.repository == 'apache/logging-parent' && github.ref_name ==
'main'
- uses:
apache/logging-parent/.github/workflows/deploy-snapshot-reusable.yaml@main
+ uses: ./.github/workflows/deploy-snapshot-reusable.yaml
# Secrets for deployments
secrets:
NEXUS_USERNAME: ${{ secrets.NEXUS_USER }}
@@ -60,7 +60,7 @@ jobs:
deploy-release:
needs: build
if: github.repository == 'apache/logging-parent' &&
startsWith(github.ref_name, 'release/')
- uses:
apache/logging-parent/.github/workflows/deploy-release-reusable.yaml@main
+ uses: ./.github/workflows/deploy-release-reusable.yaml
# Secrets for deployments
secrets:
GPG_SECRET_KEY: ${{ secrets.LOGGING_GPG_SECRET_KEY }}
diff --git a/.github/workflows/deploy-site.yaml
b/.github/workflows/deploy-site.yaml
index d2c09ca..13a5172 100644
--- a/.github/workflows/deploy-site.yaml
+++ b/.github/workflows/deploy-site.yaml
@@ -53,7 +53,7 @@ jobs:
deploy-site-stg:
if: github.repository == 'apache/logging-parent' && github.ref_name ==
'main'
- uses:
apache/logging-parent/.github/workflows/deploy-site-reusable.yaml@main
+ uses: ./.github/workflows/deploy-site-reusable.yaml
# Secrets for committing the generated site
secrets:
GPG_SECRET_KEY: ${{ secrets.LOGGING_GPG_SECRET_KEY }}
@@ -70,7 +70,7 @@ jobs:
deploy-site-pro:
if: github.repository == 'apache/logging-parent' && github.ref_name ==
'main-site-pro'
- uses:
apache/logging-parent/.github/workflows/deploy-site-reusable.yaml@main
+ uses: ./.github/workflows/deploy-site-reusable.yaml
# Secrets for committing the generated site
secrets:
GPG_SECRET_KEY: ${{ secrets.LOGGING_GPG_SECRET_KEY }}
@@ -101,7 +101,7 @@ jobs:
deploy-site-rel:
needs: export-version
- uses:
apache/logging-parent/.github/workflows/deploy-site-reusable.yaml@main
+ uses: ./.github/workflows/deploy-site-reusable.yaml
# Secrets for committing the generated site
secrets:
GPG_SECRET_KEY: ${{ secrets.LOGGING_GPG_SECRET_KEY }}
diff --git a/.github/workflows/merge-dependabot.yaml
b/.github/workflows/merge-dependabot.yaml
index 5659155..2d611cc 100644
--- a/.github/workflows/merge-dependabot.yaml
+++ b/.github/workflows/merge-dependabot.yaml
@@ -30,11 +30,11 @@ jobs:
build:
if: github.repository == 'apache/logging-parent' && github.event_name ==
'pull_request_target' && github.actor == 'dependabot[bot]'
- uses: apache/logging-parent/.github/workflows/build-reusable.yaml@main
+ uses: ./.github/workflows/build-reusable.yaml
merge-dependabot:
needs: build
- uses:
apache/logging-parent/.github/workflows/merge-dependabot-reusable.yaml@main
+ uses: ./.github/workflows/merge-dependabot-reusable.yaml
permissions:
contents: write # to push
changelog commits
pull-requests: write # to close
the PR
diff --git a/.github/workflows/build.yaml
b/src/site/antora/modules/ROOT/examples/build.yaml
similarity index 51%
copy from .github/workflows/build.yaml
copy to src/site/antora/modules/ROOT/examples/build.yaml
index f7a0a46..24eedfd 100644
--- a/.github/workflows/build.yaml
+++ b/src/site/antora/modules/ROOT/examples/build.yaml
@@ -20,47 +20,41 @@ name: build
on:
push:
branches:
- - "main"
- - "release/*"
- paths-ignore:
- - "**.adoc"
- - "**.md"
- - "**.txt"
+ - "2.x"
+ - "release/2*"
pull_request:
- paths-ignore:
- - "**.adoc"
- - "**.md"
- - "**.txt"
-
-# If the branch is `main`, run once per commit.
-# If the branch is `release/*`, allow only one concurrent run.
-concurrency:
- group: ${{ github.ref_name == 'main' && github.ref || github.ref_name }}
- cancel-in-progress: true
permissions: read-all
jobs:
+# tag::build[]
build:
- if: github.actor != 'dependabot[bot]'
- uses: apache/logging-parent/.github/workflows/build-reusable.yaml@main
+ uses:
apache/logging-parent/.github/workflows/build-reusable.yaml@rel/{project-version}
+ secrets:
+ DV_ACCESS_TOKEN: ${{ startsWith(github.ref_name, 'release/') && '' ||
secrets.DEVELOCITY_ACCESS_KEY }}
with:
site-enabled: true
+ reproducibility-check-enabled: false
+ develocity-enabled: ${{ ! startsWith(github.ref_name, 'release/') }}
+# end::build[]
+# tag::deploy-snapshot[]
deploy-snapshot:
needs: build
- if: github.repository == 'apache/logging-parent' && github.ref_name ==
'main'
- uses:
apache/logging-parent/.github/workflows/deploy-snapshot-reusable.yaml@main
+ if: github.repository == 'apache/logging-log4j2' && github.ref_name ==
'2.x'
+ uses:
apache/logging-parent/.github/workflows/deploy-snapshot-reusable.yaml@rel/{project-version}
# Secrets for deployments
secrets:
NEXUS_USERNAME: ${{ secrets.NEXUS_USER }}
NEXUS_PASSWORD: ${{ secrets.NEXUS_PW }}
+# end::deploy-snapshot[]
+# tag::deploy-release[]
deploy-release:
needs: build
- if: github.repository == 'apache/logging-parent' &&
startsWith(github.ref_name, 'release/')
- uses:
apache/logging-parent/.github/workflows/deploy-release-reusable.yaml@main
+ if: github.repository == 'apache/logging-log4j2' &&
startsWith(github.ref_name, 'release/')
+ uses:
apache/logging-parent/.github/workflows/deploy-release-reusable.yaml@rel/{project-version}
# Secrets for deployments
secrets:
GPG_SECRET_KEY: ${{ secrets.LOGGING_GPG_SECRET_KEY }}
@@ -72,4 +66,29 @@ jobs:
permissions:
contents: write
with:
- project-id: logging-parent
+ project-id: log4j
+# end::deploy-release[]
+
+# tag::verify-reproducibility-snapshot[]
+ verify-reproducibility-snapshot:
+ needs: deploy-snapshot
+ name: "verify-reproducibility (${{
needs.deploy-snapshot.outputs.project-version }})"
+ uses:
apache/logging-parent/.github/workflows/verify-reproducibility-reusable.yaml@rel/{project-version}
+ with:
+ # Reference repository
+ nexus-url: https://repository.apache.org/content/groups/snapshots
+ # Encode the `runs-on` input as JSON array
+ runs-on: '["ubuntu-latest", "macos-latest"]'
+# end::verify-reproducibility-snapshot[]
+
+# tag::verify-reproducibility-release[]
+ verify-reproducibility-release:
+ needs: deploy-release
+ name: "verify-reproducibility (${{
needs.deploy-release.outputs.project-version }})"
+ uses:
apache/logging-parent/.github/workflows/verify-reproducibility-reusable.yaml@rel/{project-version}
+ with:
+ # Reference repository
+ nexus-url: ${{ needs.deploy-release.outputs.nexus-url }}
+ # Encode the `runs-on` input as JSON array
+ runs-on: '["ubuntu-latest", "macos-latest"]'
+# end::verify-reproducibility-release[]
diff --git a/.github/workflows/deploy-site.yaml
b/src/site/antora/modules/ROOT/examples/deploy-site.yaml
similarity index 64%
copy from .github/workflows/deploy-site.yaml
copy to src/site/antora/modules/ROOT/examples/deploy-site.yaml
index d2c09ca..68d6e94 100644
--- a/.github/workflows/deploy-site.yaml
+++ b/src/site/antora/modules/ROOT/examples/deploy-site.yaml
@@ -20,11 +20,9 @@ name: deploy-site
on:
push:
branches:
- - "main"
- - "main-site-pro"
- - "release/*"
- # FIXME: Remove before a merge
- - "feature/366-npm-shrinkwrap"
+ - "2.x"
+ - "2.x-site-pro"
+ - "release/2*"
paths-ignore:
- "**.md"
- "**.txt"
@@ -33,27 +31,10 @@ permissions: read-all
jobs:
- # FIXME: This job was only created for PR #367 and should be removed before
the PR is merged
- deploy-site-test:
- if: github.repository == 'apache/logging-parent' && github.ref_name ==
'feature/366-npm-shrinkwrap'
- uses:
apache/logging-parent/.github/workflows/deploy-site-reusable.yaml@feature/366-npm-shrinkwrap
- # Secrets for committing the generated site
- secrets:
- GPG_SECRET_KEY: ${{ secrets.LOGGING_GPG_SECRET_KEY }}
- # Write permissions for committing the generated site
- permissions:
- contents: write
- with:
- asf-yaml-content: |
- staging:
- profile: test
- whoami: test-site-stg-out
- subdir: content/logging-parent-test
- target-branch: test-site-stg-out
-
+# tag::snapshot[]
deploy-site-stg:
- if: github.repository == 'apache/logging-parent' && github.ref_name ==
'main'
- uses:
apache/logging-parent/.github/workflows/deploy-site-reusable.yaml@main
+ if: github.repository == 'apache/logging-log4j2' && github.ref_name ==
'2.x'
+ uses:
apache/logging-parent/.github/workflows/deploy-site-reusable.yaml@rel/{project-version}
# Secrets for committing the generated site
secrets:
GPG_SECRET_KEY: ${{ secrets.LOGGING_GPG_SECRET_KEY }}
@@ -65,12 +46,15 @@ jobs:
staging:
profile: ~
whoami: ${{ github.ref_name }}-site-stg-out
- subdir: content/logging-parent
+ subdir: content/log4j/2.x
+ install-required: true
target-branch: ${{ github.ref_name }}-site-stg-out
+# end::snapshot[]
+# tag::production[]
deploy-site-pro:
- if: github.repository == 'apache/logging-parent' && github.ref_name ==
'main-site-pro'
- uses:
apache/logging-parent/.github/workflows/deploy-site-reusable.yaml@main
+ if: github.repository == 'apache/logging-log4j2' && github.ref_name ==
'2.x-site-pro'
+ uses:
apache/logging-parent/.github/workflows/deploy-site-reusable.yaml@rel/12.1.0
# Secrets for committing the generated site
secrets:
GPG_SECRET_KEY: ${{ secrets.LOGGING_GPG_SECRET_KEY }}
@@ -82,26 +66,27 @@ jobs:
publish:
profile: ~
whoami: ${{ github.ref_name }}-out
- subdir: content/logging-parent
+ subdir: content/log4j/2.x
+ install-required: true
target-branch: ${{ github.ref_name }}-out
+# end::production[]
+# tag::release-candidate[]
export-version:
- if: github.repository == 'apache/logging-parent' &&
startsWith(github.ref_name, 'release/')
+ if: github.repository == 'apache/logging-log4j2' &&
startsWith(github.ref_name, 'release/')
runs-on: ubuntu-latest
outputs:
version: ${{ steps.export-version.outputs.version }}
steps:
- name: Export version
id: export-version
- env:
- REF_NAME: ${{ github.ref_name }}
run: |
- version=$(echo "$REF_NAME" | sed 's/^release\///' | tr -d '\r\n')
+ version=$(echo "${{ github.ref_name }}" | sed 's/^release\///')
echo "version=$version" >> "$GITHUB_OUTPUT"
deploy-site-rel:
needs: export-version
- uses:
apache/logging-parent/.github/workflows/deploy-site-reusable.yaml@main
+ uses:
apache/logging-parent/.github/workflows/deploy-site-reusable.yaml@rel/{project-version}
# Secrets for committing the generated site
secrets:
GPG_SECRET_KEY: ${{ secrets.LOGGING_GPG_SECRET_KEY }}
@@ -113,5 +98,7 @@ jobs:
staging:
profile: ~
whoami: ${{ github.ref_name }}-site-stg-out
- subdir: content/logging-parent-${{
needs.export-version.outputs.version }}
+ subdir: content/log4j/${{ needs.export-version.outputs.version }}
+ install-required: true
target-branch: ${{ github.ref_name }}-site-stg-out
+# end::release-candidate[]
diff --git a/src/site/antora/modules/ROOT/pages/features.adoc
b/src/site/antora/modules/ROOT/pages/features.adoc
index 3101ad6..024e9d9 100644
--- a/src/site/antora/modules/ROOT/pages/features.adoc
+++ b/src/site/antora/modules/ROOT/pages/features.adoc
@@ -49,30 +49,11 @@ This VDR is accessible through the following URL:
{logging-services-url}/cyclone
[#reusable-workflows]
== Reusable GitHub Actions workflows
-The provided reusable GitHub Actions workflows feature the following
conveniences:
+Logging Parent publishes several
+https://docs.github.com/en/actions/sharing-automations/reusing-workflows[reusable
workflows]
+that can be used from other repositories.
-{project-github-url}/blob/main/.github/workflows/build-reusable.yaml[`build-reusable.yaml`]::
-* Compiles using the specified Java compiler version
-* Submits build scans to the Develocity server
-
-{project-github-url}/blob/main/.github/workflows/deploy-release-reusable.yaml[`deploy-release-reusable.yaml`]::
-* Deploys release artifacts
-* Updates `revision` and `project.build.outputTimestamp` Maven properties
-* Generates the distribution ZIP containing Git-tracked sources, binary
attachments, `NOTICE.txt`, etc.
-* Generates the release vote & announcement emails
-* Uploads the distribution ZIP and emails to SVN
-
-{project-github-url}/blob/main/.github/workflows/deploy-site-reusable.yaml[`deploy-site-reusable.yaml`]::
-* Builds and deploys the website
-
-{project-github-url}/blob/main/.github/workflows/deploy-snapshot-reusable.yaml[`deploy-snapshot-reusable.yaml`]::
-* Deploys SNAPSHOT artifacts
-
-{project-github-url}/blob/main/.github/workflows/merge-dependabot-reusable.yaml[`merge-dependabot-reusable.yaml`]::
-* Merges `dependabot` PRs along with changelog entries
-
-{project-github-url}/blob/main/.github/workflows/merge-dependabot-reusable.yaml[`verify-reproducibility-reusable.yaml`]::
-* Verifies reproducibility of a previous deployment workflow.
+See xref:workflows.adoc[] for details.
[#release-instructions]
=== Release instructions
diff --git a/src/site/antora/modules/ROOT/pages/usage.adoc
b/src/site/antora/modules/ROOT/pages/usage.adoc
index 2b0ce49..dccbcf7 100644
--- a/src/site/antora/modules/ROOT/pages/usage.adoc
+++ b/src/site/antora/modules/ROOT/pages/usage.adoc
@@ -22,7 +22,9 @@ You can use {project-name} as follows:
. Add `org.apache.logging:logging-parent:{project-version}` as a `parent` to
your `pom.xml`
. You may need to add `.mvn/jvm.config` to your project. See
https://github.com/apache/logging-log4j2/blob/2.x/.mvn/jvm.config[this] as an
example.
. Check if `./mvnw verify` succeeds, otherwise make necessary changes
-. Copy and adapt the support files (`.gitignore`,
`.github/workflows/build.yaml`, etc.)
+. Copy and adapt the support files (`.gitignore`, `.gitattributes`, etc.)
+. Create workflows using reusable workflows.
+ See xref:workflows.adoc[] for more details.
. Copy and adapt Log4j Changelog files:
*** `src/changelog/.<majorVersion>.x.x/.release-notes.adoc.ftl`
*** `src/changelog/.changelog.adoc.ftl`
diff --git a/src/site/antora/modules/ROOT/pages/workflows.adoc
b/src/site/antora/modules/ROOT/pages/workflows.adoc
new file mode 100644
index 0000000..e9ed9f9
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/workflows.adoc
@@ -0,0 +1,142 @@
+////
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+////
+
+:examples-base-link:
https://github.com/apache/logging-parent/tree/main/src/site/antora/modules/ROOT/examples
+
+[#reusable-workflows]
+= Reusable GitHub Actions workflows
+
+The Logging Parent project provides the following reusable GitHub Actions
workflows:
+
+* <<build>>
+* <<deploy-release>>
+* <<deploy-site>>
+* <<deploy-snapshot>>
+* <<merge-dependabot>>
+* <<verify-reproducibility>>
+
+[#build]
+==
{project-github-url}/blob/main/.github/workflows/build-reusable.yaml[`build-reusable.yaml`]
+
+This workflow:
+
+* Compiles using the specified Java compiler version
+* Submits build scans to the Develocity server
+
+[#build-examples]
+=== Examples
+
+.Snippet from an {examples-base-link}/build.yaml[example `build.yaml`] using
this workflow
+[source,yaml,subs=+attributes]
+----
+include::example$build.yaml[tag=build,indent=0]
+----
+
+[#deploy-snapshot]
+==
{project-github-url}/blob/main/.github/workflows/deploy-snapshot-reusable.yaml[`deploy-snapshot-reusable.yaml`]
+
+This workflow deploys SNAPSHOT artifacts.
+
+[#deploy-snapshot-examples]
+=== Examples
+
+.Snippet from an {examples-base-link}/build.yaml[example `build.yaml`] using
this workflow
+[source,yaml,subs=+attributes]
+----
+include::example$build.yaml[tag=deploy-snapshot,indent=0]
+----
+
+[#deploy-release]
+==
{project-github-url}/blob/main/.github/workflows/deploy-release-reusable.yaml[`deploy-release-reusable.yaml`]
+
+This workflow:
+
+* Deploys release artifacts
+* Updates `revision` and `project.build.outputTimestamp` Maven properties
+* Generates the distribution ZIP containing Git-tracked sources, binary
attachments, `NOTICE.txt`, etc.
+* Generates the release vote & announcement emails
+* Uploads the distribution ZIP and emails to SVN
+
+[#deploy-release-examples]
+=== Examples
+
+.Snippet from an {examples-base-link}/build.yaml[example `build.yaml`] using
this workflow
+[source,yaml,subs=+attributes]
+----
+include::example$build.yaml[tag=deploy-release,indent=0]
+----
+
+[#verify-reproducibility]
+==
{project-github-url}/blob/main/.github/workflows/merge-dependabot-reusable.yaml[`verify-reproducibility-reusable.yaml`]
+
+This workflow verifies the reproducibility of a previous <<deploy-snapshot>>
or <<deploy-release>> workflow.
+
+[#verify-reproducibility-examples]
+=== Examples
+
+To verify the reproducibility of a snapshot, you can use:
+
+.Snippet from an {examples-base-link}/build.yaml[example `build.yaml`] using
this workflow
+[source,yaml,subs=+attributes]
+----
+include::example$build.yaml[tag=verify-reproducibility-snapshot,indent=0]
+----
+
+To verify the reproducibility of a release, you can use:
+
+.Snippet from an {examples-base-link}/build.yaml[example `build.yaml`] using
this workflow
+[source,yaml,subs=+attributes]
+----
+include::example$build.yaml[tag=verify-reproducibility-release,indent=0]
+----
+
+[#merge-dependabot]
+==
{project-github-url}/blob/main/.github/workflows/merge-dependabot-reusable.yaml[`merge-dependabot-reusable.yaml`]
+
+Merges Dependabot PRs along with changelog entries.
+
+[#deploy-site]
+==
{project-github-url}/blob/main/.github/workflows/deploy-site-reusable.yaml[`deploy-site-reusable.yaml`]
+
+This workflow builds and deploys the website.
+
+[#deploy-site-examples]
+=== Examples
+
+To update the staging website, you can use:
+
+.Snippet from an {examples-base-link}/deploy-site.yaml[example
`deploy-site.yaml`] using this workflow
+[source,yaml,subs=+attributes]
+----
+include::example$deploy-site.yaml[tag=snapshot,indent=0]
+----
+
+To stage a separate website for a release candidate, you can use:
+
+.Snippet from an {examples-base-link}/deploy-site.yaml[example
`deploy-site.yaml`] using this workflow
+[source,yaml,subs=+attributes]
+----
+include::example$deploy-site.yaml[tag=release-candidate,indent=0]
+----
+
+To update the production website after a release, you can use:
+
+.Snippet from an {examples-base-link}/deploy-site.yaml[example
`deploy-site.yaml`] using this workflow
+[source,yaml,subs=+attributes]
+----
+include::example$deploy-site.yaml[tag=production,indent=0]
+----
