[docs] Clarify changelog workflow permissions (#118) (#120)

* [docs] Clarify changelog workflow permissions (#118)

* Update wiki submodule pointer for PR #120

* [changelog] Add release workflow permissions note (#118)

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.github/wiki

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Document required GitHub Actions permissions for changelog release automation (#118)
+
 ## [1.12.0] - 2026-04-19
 
 ### Added

CHANGELOG.md

@@ -170,6 +170,14 @@ changelog automation for pull-request validation and release preparation, so
 consumer repositories can adopt the same changelog-driven release flow without
 copying workflow logic by hand.
 
+The release workflow is intentionally two-step: `workflow_dispatch` prepares a
+`release/v...` pull request, and merging that release pull request publishes
+the GitHub release and tag. Consumer repositories must enable GitHub Actions
+**Read and write permissions** and **Allow GitHub Actions to create and approve
+pull requests** under `Settings -> Actions -> General`. If those controls are
+disabled, an organization or repository admin must unlock them before the
+release-preparation workflow can create pull requests.
+
 This repository also keeps role-based project agents in `.agents/agents`. They
 are mirrored through `.github/agents` for GitHub-oriented discovery, while the
 packaged `.agents/skills` directory remains the consumer-facing procedural

README.md

@@ -38,12 +38,21 @@ Once this is done, the wiki can be cloned as a submodule and synchronized by the
 Workflow Permissions
 --------------------
 
-GitHub Actions must have permission to push changes to your repository (for Wiki updates and GitHub Pages deployments).
+GitHub Actions must have permission to push changes to your repository and, for
+the changelog release flow, to open release-preparation pull requests.
 
 1.  Go to **Settings** > **Actions** > **General**.
 2.  Scroll down to **Workflow permissions**.
 3.  Select **Read and write permissions**.
-4.  Click **Save**.
+4.  Enable **Allow GitHub Actions to create and approve pull requests**.
+5.  Click **Save**.
 
 .. warning::
-   Without these permissions, the ``wiki.yml`` and ``reports.yml`` workflows will fail when attempting to deploy content.
+   Without these permissions, the ``wiki.yml`` and ``reports.yml`` workflows will fail when attempting to deploy content, and the ``changelog.yml`` workflow will fail when trying to open a ``release/v...`` pull request.
+
+.. note::
+   If the permission controls are disabled or grayed out, the repository is
+   usually constrained by organization policy or by missing admin access. This
+   is separate from branch protection. Branch protection affects whether the
+   generated release pull request can be merged, while workflow permissions
+   affect whether GitHub Actions can create that pull request at all.

docs/configuration/repository-setup.rst

@@ -51,6 +51,11 @@ The expected flow is:
 6. let the merged release workflow create or update the GitHub release and tag from the released changelog section;
 7. confirm Packagist, reports, and wiki publication.
 
+This means an ordinary feature or bug-fix pull request merged into ``main``
+does **not** publish a GitHub release by itself. Publication happens only after
+the dedicated ``release/v...`` pull request created by the changelog workflow
+is merged.
+
 Do not retag an existing published version. If a release needs correction,
 prepare a follow-up changelog entry, open a new release-preparation pull
 request, and publish a new version tag.
@@ -113,6 +118,26 @@ matching released changelog section. Those notes SHOULD include:
 - documentation and workflow changes that affect consumer repositories;
 - verification performed before the release.
 
+Workflow Permissions
+--------------------
+
+The manual release-preparation step depends on GitHub Actions being allowed to
+open pull requests on behalf of the repository workflow token.
+
+Configure the repository under **Settings** > **Actions** > **General**:
+
+1. enable **Read and write permissions** under **Workflow permissions**;
+2. enable **Allow GitHub Actions to create and approve pull requests**.
+
+If either control appears disabled or grayed out, the restriction is usually
+coming from repository permissions or organization policy rather than branch
+protection. In that case, an organization or repository administrator MUST
+adjust the policy before the workflow can prepare release pull requests.
+
+Branch protection matters later, when the generated ``release/v...`` pull
+request is reviewed and merged, but it does not control whether the workflow is
+allowed to create that pull request in the first place.
+
 Packagist Publication
 ---------------------
 

docs/internals/release-publishing.rst

@@ -100,16 +100,27 @@ wrapper in ``resources/github-actions/changelog.yml``.
     *   Writes a release-notes preview file to ``.dev-tools/release-notes.md`` with
         ``composer dev-tools changelog:show -- <version>``.
     *   Opens or updates a release-preparation pull request instead of committing directly to ``main``.
+    *   Requires repository Actions permissions that allow the workflow token to create pull requests.
 *   **Merged Release Pull Requests**:
     *   Detects merged branches that match the configured release branch prefix.
     *   Renders the released changelog section with ``composer dev-tools changelog:show -- <version>``.
     *   Creates or updates the Git tag and GitHub release with the rendered changelog section as the release body.
+    *   Does **not** run for ordinary feature or fix pull requests merged into ``main``.
 
 **Inputs:**
 *   ``changelog-file``: managed changelog path, default ``CHANGELOG.md``.
 *   ``version``: optional explicit version for manual release preparation.
 *   ``release-branch-prefix``: release branch prefix, default ``release/v``.
 
+**Repository prerequisites:**
+*   Go to **Settings** > **Actions** > **General**.
+*   Under **Workflow permissions**, enable **Read and write permissions**.
+*   Enable **Allow GitHub Actions to create and approve pull requests**.
+*   If either control is disabled or grayed out, the repository is likely constrained by organization-level policy or missing admin permission. In that case, an organization or repository admin must unlock the setting before manual release preparation can open a release pull request.
+
+.. note::
+   Branch protection is not what blocks the release-preparation workflow from opening a pull request. Branch protection affects the merge of the ``release/v...`` pull request later in the flow. The gray or disabled workflow-permission controls come from repository permissions or organization policy.
+
 Maintenance Workflows
 ---------------------