This is an automated email from the ASF dual-hosted git repository. ppkarwasz pushed a commit to branch feat/draft-trick-doc in repository https://gitbox.apache.org/repos/asf/logging-parent.git
commit cc23624023cff44ad1f5ecc33bd6f6b3fefee9be Author: Piotr P. Karwasz <[email protected]> AuthorDate: Sun May 3 15:42:26 2026 +0200 Document “draft trick” This change documents the “draft trick” introduced in #475 and applies it to the `main` branch. --- .github/workflows/build.yaml | 7 +++ .github/workflows/codeql-analysis.yaml | 7 +++ .github/workflows/process-dependabot.yaml | 3 -- .../modules/ROOT/examples/process-dependabot.yaml | 8 ++-- src/site/antora/modules/ROOT/pages/workflows.adoc | 52 +++++++++++++--------- 5 files changed, 47 insertions(+), 30 deletions(-) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index a87c0c8..d306578 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -26,6 +26,13 @@ on: - "**.md" - "**.txt" pull_request: + types: + # Standard types + - opened + - synchronize + - reopened + # Used in Dependabot PRs to retrigger required workflows + - ready_for_review # If the branch is `main`, run once per commit. # If the branch is `release/*`, allow only one concurrent run. diff --git a/.github/workflows/codeql-analysis.yaml b/.github/workflows/codeql-analysis.yaml index 9aff2e6..532d8ac 100644 --- a/.github/workflows/codeql-analysis.yaml +++ b/.github/workflows/codeql-analysis.yaml @@ -26,6 +26,13 @@ on: pull_request: branches: - "main" + types: + # Standard types + - opened + - synchronize + - reopened + # Used in Dependabot PRs to retrigger required workflows + - ready_for_review schedule: - cron: '32 12 * * 5' diff --git a/.github/workflows/process-dependabot.yaml b/.github/workflows/process-dependabot.yaml index 02ec23a..0004555 100644 --- a/.github/workflows/process-dependabot.yaml +++ b/.github/workflows/process-dependabot.yaml @@ -43,9 +43,6 @@ jobs: # This requires the following two permissions: contents: write pull-requests: write - secrets: - # This token will be used to push new content to the repo and trigger workflows again - RECURSIVE_TOKEN: ${{ secrets.DEPENDABOT_TOKEN }} with: # The path to the changelog directory for the current development branch. changelog-path: src/changelog/.12.x.x diff --git a/src/site/antora/modules/ROOT/examples/process-dependabot.yaml b/src/site/antora/modules/ROOT/examples/process-dependabot.yaml index 077a581..a55cc4c 100644 --- a/src/site/antora/modules/ROOT/examples/process-dependabot.yaml +++ b/src/site/antora/modules/ROOT/examples/process-dependabot.yaml @@ -38,13 +38,11 @@ jobs: }} uses: apache/logging-parent/.github/workflows/process-dependabot-reusable.yaml@{project-gha-version} permissions: - # The default GITHUB_TOKEN will be used to enable the "auto-merge" on the PR - # This requires the following two permissions: + # Append the changelog commit contents: write + # Convert the PR into draft pull-requests: write - secrets: - RECURSIVE_TOKEN: ${{ secrets.DEPENDABOT_TOKEN }} with: # The path to the changelog directory for the current development branch. - changelog-path: src/changelog/.2.x.x + changelog-path: src/changelog/.12.x.x # end::process-dependabot[] diff --git a/src/site/antora/modules/ROOT/pages/workflows.adoc b/src/site/antora/modules/ROOT/pages/workflows.adoc index 2fbb7dd..4679f2c 100644 --- a/src/site/antora/modules/ROOT/pages/workflows.adoc +++ b/src/site/antora/modules/ROOT/pages/workflows.adoc @@ -126,33 +126,41 @@ include::example$analyze-dependabot.yaml[tag=analyze-dependabot,indent=0] Helps to process Dependabot pull requests by: -* Generating changelog entries for the updated dependencies. -* Enabling the "auto-merge" option for the pull request. +* Generating changelog entries for the updated dependencies and committing them to the PR branch. +* Switching the pull request into “draft mode”. -The workflow needs the following privileged tokens: +The workflow only needs the default `GITHUB_TOKEN` with `contents: write` and `pull-requests: write` permissions. +No Personal Access Token (PAT) is required. -`GITHUB_TOKEN`:: -The default GitHub token with `contents:write` and `pull-requests: write` permissions, -used to enable auto-merge on pull requests. -+ -This token is automatically provided by GitHub Actions, but needs to be configured in the `permissions` property. - -`RECURSIVE_TOKEN`:: -A GitHub token required to push generated changelog files as a new commit to the repository. -The default `GITHUB_TOKEN` can **not** be used, -as it will not trigger required check runs and will prevent the pull request from being merged. -A Personal Access Token (PAT) with `contents:write` permission must be provided instead. -+ -The token must be passed as a secret named `RECURSIVE_TOKEN`. - -This workflow is designed to be triggered by the `workflow_run` event, -as soon as the <<analyze-dependabot>> workflow completes. +This workflow is designed to be triggered by the `workflow_run` event, as soon as the <<analyze-dependabot>> workflow completes. [NOTE] ==== -When this workflow is triggered by `workflow_run`, -GitHub Actions uses the "Actions" secret context instead of "Dependabot" secrets, -even if the `github.actor` is `dependabot[bot]`. +Avoiding a PAT is a deliberate security choice, but it has a consequence: pushes made with `GITHUB_TOKEN` do not retrigger workflows (GitHub anti-recursion rule), so the changelog commit cannot re-run the required checks on its own. +This reusable workflow therefore parks the PR in “draft mode” and stops there. + +The expected flow for each Dependabot PR is: + +. The reusable workflow appends the changelog commit and converts the PR into draft. +. A maintainer reviews the change, clicks *Ready for review*, and enables *Auto-merge*. +. The required-check workflows re-run against the new HEAD; once they pass, *Auto-merge* completes the merge without further manual action. + +For step 3 to work, every workflow providing a required check must subscribe to `ready_for_review`: + +[source,yaml] +---- +on: + pull_request: + types: + # Standard types + - opened + - synchronize + - reopened + # Used in Dependabot PRs to retrigger required workflows + - ready_for_review +---- + +This reusable workflow does **not** enable “Auto-merge”; a maintainer must do that by hand. ==== .Snippet from an {examples-base-link}/process-dependabot.yaml[example `process-dependabot.yaml`] using this workflow
