From e229e3abd221b3e894450cf1e48e8f7a4ee1d06d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 23 Jan 2026 05:01:50 +0000 Subject: [PATCH 1/5] Initial plan From a5cc049f35429a2d796c5a4a425f3f0ee9d43358 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 23 Jan 2026 05:05:46 +0000 Subject: [PATCH 2/5] Add workflow to trigger python-docs-pdf on Doc/ changes Co-authored-by: m-aciek <9288014+m-aciek@users.noreply.github.com> --- .github/workflows/README-trigger-docs-pdf.md | 83 ++++++++++++++++++++ .github/workflows/trigger-docs-pdf.yml | 29 +++++++ 2 files changed, 112 insertions(+) create mode 100644 .github/workflows/README-trigger-docs-pdf.md create mode 100644 .github/workflows/trigger-docs-pdf.yml diff --git a/.github/workflows/README-trigger-docs-pdf.md b/.github/workflows/README-trigger-docs-pdf.md new file mode 100644 index 00000000000000..dfd767e84ba0d0 --- /dev/null +++ b/.github/workflows/README-trigger-docs-pdf.md @@ -0,0 +1,83 @@ +# Trigger Docs PDF Build Workflow + +## Overview + +This workflow (`trigger-docs-pdf.yml`) automatically triggers the python-docs-pdf repository's build workflow when documentation changes are pushed to the CPython repository. + +## Workflow Trigger Conditions + +The workflow runs when: +- A commit is pushed to `main` or any `3.*` branch (e.g., `3.13`, `3.12`, etc.) +- The commit modifies any files under the `Doc/` directory + +## How It Works + +1. When the trigger conditions are met, the workflow sends a `repository_dispatch` event to the `m-aciek/python-docs-pdf` repository +2. The event includes: + - `event_type`: `cpython_docs_updated` + - `branch`: The branch name where the commit was pushed + - `repository`: The full repository name (e.g., `m-aciek/cpython`) + - `sha`: The commit SHA + - `commit_message`: The commit message + +## Required Configuration + +### 1. Personal Access Token (PAT) + +This workflow requires a Personal Access Token with appropriate permissions to trigger workflows in the target repository. + +**Steps to set up:** + +1. Create a GitHub Personal Access Token with the following scopes: + - `repo` (Full control of private repositories) OR + - `public_repo` (Access public repositories) if both repos are public + - The token needs permission to trigger workflows in the `m-aciek/python-docs-pdf` repository + +2. Add the token as a repository secret: + - Go to the CPython repository settings + - Navigate to Secrets and variables → Actions + - Create a new repository secret named `DOCS_PDF_TRIGGER_TOKEN` + - Paste the Personal Access Token as the value + +### 2. Target Repository Configuration + +The `m-aciek/python-docs-pdf` repository's `build.yaml` workflow needs to be updated to accept `repository_dispatch` events. + +Add the following to the `on:` section of `.github/workflows/build.yaml`: + +```yaml +on: + workflow_dispatch: + # ... existing workflow_dispatch configuration ... + repository_dispatch: + types: [cpython_docs_updated] +``` + +Then, update the workflow to use the branch from the client payload: + +```yaml +jobs: + build: + runs-on: ubuntu-latest + steps: + # ... other steps ... + - uses: actions/checkout@master + with: + repository: python/cpython + ref: ${{ github.event.client_payload.branch || github.event.inputs.tag }} + # ... remaining steps ... +``` + +## Testing + +To test this workflow without making changes to documentation: + +1. You can manually trigger workflows using the GitHub API +2. Or make a small change to a file in the `Doc/` directory on a test branch +3. Push to `main` or a `3.*` branch to see the workflow trigger + +## Troubleshooting + +- **Workflow doesn't trigger**: Ensure the `DOCS_PDF_TRIGGER_TOKEN` secret is properly configured +- **403 Forbidden errors**: The PAT may not have sufficient permissions or may have expired +- **Target workflow doesn't run**: Verify the target repository has added `repository_dispatch` trigger support diff --git a/.github/workflows/trigger-docs-pdf.yml b/.github/workflows/trigger-docs-pdf.yml new file mode 100644 index 00000000000000..eeba1591761b98 --- /dev/null +++ b/.github/workflows/trigger-docs-pdf.yml @@ -0,0 +1,29 @@ +name: Trigger Docs PDF Build + +on: + push: + branches: + - 'main' + - '3.*' + paths: + - 'Doc/**' + +permissions: + contents: read + +jobs: + trigger-pdf-build: + name: Trigger python-docs-pdf workflow + runs-on: ubuntu-latest + steps: + - name: Trigger repository_dispatch event + env: + COMMIT_MESSAGE: ${{ github.event.head_commit.message }} + run: | + curl -L \ + -X POST \ + -H "Accept: application/vnd.github+json" \ + -H "Authorization: Bearer ${{ secrets.DOCS_PDF_TRIGGER_TOKEN }}" \ + -H "X-GitHub-Api-Version: 2022-11-28" \ + https://api.github.com/repos/m-aciek/python-docs-pdf/dispatches \ + -d "{\"event_type\":\"cpython_docs_updated\",\"client_payload\":{\"branch\":\"${{ github.ref_name }}\",\"repository\":\"${{ github.repository }}\",\"sha\":\"${{ github.sha }}\",\"commit_message\":\"${COMMIT_MESSAGE}\"}}" From 94bf6a919bb7fc7ed20f4f1101efb3c2953292f2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 23 Jan 2026 05:07:17 +0000 Subject: [PATCH 3/5] Fix security issues in trigger workflow - use jq for JSON escaping and update checkout version Co-authored-by: m-aciek <9288014+m-aciek@users.noreply.github.com> --- .github/workflows/README-trigger-docs-pdf.md | 2 +- .github/workflows/trigger-docs-pdf.yml | 23 +++++++++++++++++++- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/.github/workflows/README-trigger-docs-pdf.md b/.github/workflows/README-trigger-docs-pdf.md index dfd767e84ba0d0..4c1d1b139b8db4 100644 --- a/.github/workflows/README-trigger-docs-pdf.md +++ b/.github/workflows/README-trigger-docs-pdf.md @@ -61,7 +61,7 @@ jobs: runs-on: ubuntu-latest steps: # ... other steps ... - - uses: actions/checkout@master + - uses: actions/checkout@v6 with: repository: python/cpython ref: ${{ github.event.client_payload.branch || github.event.inputs.tag }} diff --git a/.github/workflows/trigger-docs-pdf.yml b/.github/workflows/trigger-docs-pdf.yml index eeba1591761b98..c72023a941a253 100644 --- a/.github/workflows/trigger-docs-pdf.yml +++ b/.github/workflows/trigger-docs-pdf.yml @@ -18,12 +18,33 @@ jobs: steps: - name: Trigger repository_dispatch event env: + BRANCH: ${{ github.ref_name }} + REPOSITORY: ${{ github.repository }} + SHA: ${{ github.sha }} COMMIT_MESSAGE: ${{ github.event.head_commit.message }} run: | + # Use jq to properly escape JSON values + payload=$(jq -n \ + --arg event_type "cpython_docs_updated" \ + --arg branch "$BRANCH" \ + --arg repository "$REPOSITORY" \ + --arg sha "$SHA" \ + --arg commit_message "$COMMIT_MESSAGE" \ + '{ + event_type: $event_type, + client_payload: { + branch: $branch, + repository: $repository, + sha: $sha, + commit_message: $commit_message + } + }') + curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer ${{ secrets.DOCS_PDF_TRIGGER_TOKEN }}" \ -H "X-GitHub-Api-Version: 2022-11-28" \ + -H "Content-Type: application/json" \ https://api.github.com/repos/m-aciek/python-docs-pdf/dispatches \ - -d "{\"event_type\":\"cpython_docs_updated\",\"client_payload\":{\"branch\":\"${{ github.ref_name }}\",\"repository\":\"${{ github.repository }}\",\"sha\":\"${{ github.sha }}\",\"commit_message\":\"${COMMIT_MESSAGE}\"}}" + -d "$payload" From 01a515819971d1ab16a2faa3ecdbf788a9d295b6 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 9 Feb 2026 10:12:26 +0100 Subject: [PATCH 4/5] rename pdf to offline More formats supported --- .github/workflows/README-trigger-docs-pdf.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/README-trigger-docs-pdf.md b/.github/workflows/README-trigger-docs-pdf.md index 4c1d1b139b8db4..17d6113a55aa2e 100644 --- a/.github/workflows/README-trigger-docs-pdf.md +++ b/.github/workflows/README-trigger-docs-pdf.md @@ -1,8 +1,8 @@ -# Trigger Docs PDF Build Workflow +# Trigger Docs Offline Build Workflow ## Overview -This workflow (`trigger-docs-pdf.yml`) automatically triggers the python-docs-pdf repository's build workflow when documentation changes are pushed to the CPython repository. +This workflow (`trigger-docs-offline.yml`) automatically triggers the python-docs-offline repository's build workflow when documentation changes are pushed to the CPython repository. ## Workflow Trigger Conditions @@ -12,7 +12,7 @@ The workflow runs when: ## How It Works -1. When the trigger conditions are met, the workflow sends a `repository_dispatch` event to the `m-aciek/python-docs-pdf` repository +1. When the trigger conditions are met, the workflow sends a `repository_dispatch` event to the `m-aciek/python-docs-offline` repository 2. The event includes: - `event_type`: `cpython_docs_updated` - `branch`: The branch name where the commit was pushed @@ -31,17 +31,17 @@ This workflow requires a Personal Access Token with appropriate permissions to t 1. Create a GitHub Personal Access Token with the following scopes: - `repo` (Full control of private repositories) OR - `public_repo` (Access public repositories) if both repos are public - - The token needs permission to trigger workflows in the `m-aciek/python-docs-pdf` repository + - The token needs permission to trigger workflows in the `m-aciek/python-docs-offline` repository 2. Add the token as a repository secret: - Go to the CPython repository settings - Navigate to Secrets and variables → Actions - - Create a new repository secret named `DOCS_PDF_TRIGGER_TOKEN` + - Create a new repository secret named `DOCS_OFFLINE_TRIGGER_TOKEN` - Paste the Personal Access Token as the value ### 2. Target Repository Configuration -The `m-aciek/python-docs-pdf` repository's `build.yaml` workflow needs to be updated to accept `repository_dispatch` events. +The `m-aciek/python-docs-offline` repository's `build.yaml` workflow needs to be updated to accept `repository_dispatch` events. Add the following to the `on:` section of `.github/workflows/build.yaml`: @@ -78,6 +78,6 @@ To test this workflow without making changes to documentation: ## Troubleshooting -- **Workflow doesn't trigger**: Ensure the `DOCS_PDF_TRIGGER_TOKEN` secret is properly configured +- **Workflow doesn't trigger**: Ensure the `DOCS_OFFLINE_TRIGGER_TOKEN` secret is properly configured - **403 Forbidden errors**: The PAT may not have sufficient permissions or may have expired - **Target workflow doesn't run**: Verify the target repository has added `repository_dispatch` trigger support From 5bb8a6cbb339b9b37072e1603cd4296ccbb8c6f6 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 9 Feb 2026 10:38:17 +0100 Subject: [PATCH 5/5] Rename files pdf -> offline --- ...EADME-trigger-docs-pdf.md => README-trigger-docs-offline.md} | 0 .../{trigger-docs-pdf.yml => trigger-docs-offline.yml} | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename .github/workflows/{README-trigger-docs-pdf.md => README-trigger-docs-offline.md} (100%) rename .github/workflows/{trigger-docs-pdf.yml => trigger-docs-offline.yml} (99%) diff --git a/.github/workflows/README-trigger-docs-pdf.md b/.github/workflows/README-trigger-docs-offline.md similarity index 100% rename from .github/workflows/README-trigger-docs-pdf.md rename to .github/workflows/README-trigger-docs-offline.md diff --git a/.github/workflows/trigger-docs-pdf.yml b/.github/workflows/trigger-docs-offline.yml similarity index 99% rename from .github/workflows/trigger-docs-pdf.yml rename to .github/workflows/trigger-docs-offline.yml index c72023a941a253..543ff5ef045070 100644 --- a/.github/workflows/trigger-docs-pdf.yml +++ b/.github/workflows/trigger-docs-offline.yml @@ -39,7 +39,7 @@ jobs: commit_message: $commit_message } }') - + curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \