GHA: Unify workflows for build/test/publish documentation#2038
GHA: Unify workflows for build/test/publish documentation#2038
Conversation
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| name: Build Docs | ||
| runs-on: ubuntu-latest | ||
| timeout-minutes: 10 | ||
| steps: | ||
| - name: 📥 Checkout the repository | ||
| uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 | ||
| with: | ||
| fetch-depth: 0 | ||
|
|
||
| - name: 🐍 Install uv and set Python ${{ inputs.python-version }} | ||
| uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6 | ||
| with: | ||
| python-version: ${{ inputs.python-version }} | ||
| activate-environment: true | ||
|
|
||
| - name: 🏗️ Install dependencies | ||
| run: | | ||
| uv pip install -r pyproject.toml --group docs | ||
|
|
||
| - name: 🔑 Create GitHub App token (mkdocs) | ||
| # todo: this template need to be public for proper testing | ||
| if: inputs.insiders | ||
| id: mkdocs_token | ||
| uses: actions/create-github-app-token@29824e69f54612133e76f7eaac726eef6c875baf # v2.2.1 | ||
| with: | ||
| app-id: ${{ secrets.MKDOCS_APP_ID }} | ||
| private-key: ${{ secrets.MKDOCS_PEM }} | ||
| owner: roboflow | ||
| repositories: mkdocs-material-insiders | ||
|
|
||
| - name: 🏗️ Install mkdocs-material-insiders | ||
| if: inputs.insiders | ||
| run: | | ||
| uv pip install "git+https://roboflow:${{ steps.mkdocs_token.outputs.token }}@github.com/roboflow/mkdocs-material-insiders.git@9.5.49-insiders-4.53.14#egg=mkdocs-material[imaging]" | ||
|
|
||
| - name: 🧪 Build Docs | ||
| run: uv run mkdocs build --verbose | ||
|
|
||
| - name: 📤 Upload docs site as artifact | ||
| uses: actions/upload-artifact@4.33.0 | ||
| with: | ||
| name: docs-site | ||
| path: site/ |
Check warning
Code scanning / CodeQL
Workflow does not contain permissions Medium
Show autofix suggestion
Hide autofix suggestion
Copilot Autofix
AI 2 months ago
In general, fix this by explicitly specifying a permissions block that grants only the minimal scopes the job needs. For a docs build that only checks out the repository, installs dependencies, builds, and uploads artifacts, contents: read is sufficient; no write permissions or other scopes are required.
The best fix here is to add a workflow‑level permissions block (applies to all jobs without their own block). In .github/workflows/build-docs.yml, add:
permissions:
contents: readnear the top of the file, after the name: line and before the on: block. This restricts the GITHUB_TOKEN to read‑only access to repository contents for all jobs in this workflow, without affecting existing functionality of actions/checkout, astral-sh/setup-uv, the docs build commands, or actions/upload-artifact (which does not depend on repository write permissions).
No additional methods, imports, or definitions are needed since this is purely a configuration change in the workflow YAML.
| @@ -1,5 +1,8 @@ | ||
| name: Build Docs | ||
|
|
||
| permissions: | ||
| contents: read | ||
|
|
||
| on: | ||
| workflow_call: | ||
| inputs: |
There was a problem hiding this comment.
Pull request overview
This pull request refactors the GitHub Actions documentation workflows by introducing a reusable workflow to centralize and standardize the documentation build process across multiple workflows.
Key Changes:
- Introduced a new reusable workflow
build-docs.ymlthat handles documentation building with configurable Python versions - Updated
test-doc.ymlto call the reusable workflow instead of duplicating build steps - Updated
publish-docs.ymlto call the reusable workflow for the build phase before deployment
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
.github/workflows/build-docs.yml |
New reusable workflow that centralizes documentation building logic with configurable Python version and artifact upload |
.github/workflows/test-doc.yml |
Simplified to call the new reusable build-docs workflow, removing all inline build steps |
.github/workflows/publish-docs.yml |
Refactored to separate build and deploy phases, with build delegated to the reusable workflow |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
after/for this update, the required check needs to be updated too 🦩 |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - name: 🚀 Deploy Development Docs | ||
| if: (github.event_name == 'push' && github.ref == 'refs/heads/develop') || github.event_name == 'workflow_dispatch' | ||
| run: | | ||
| MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} uv run mike deploy --push develop | ||
| uses: peaceiris/actions-gh-pages@v4 | ||
| with: | ||
| github_token: ${{ secrets.GITHUB_TOKEN }} | ||
| publish_dir: site | ||
| destination_dir: develop | ||
|
|
||
| - name: 🚀 Deploy Release Docs | ||
| if: github.event_name == 'release' && github.event.action == 'published' | ||
| run: | | ||
| latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`) | ||
| MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} uv run mike deploy --push --update-aliases $latest_tag latest | ||
| uses: peaceiris/actions-gh-pages@v4 | ||
| with: | ||
| github_token: ${{ secrets.GITHUB_TOKEN }} | ||
| publish_dir: site | ||
| destination_dir: ${{ github.event.release.tag_name }} |
There was a problem hiding this comment.
The deployment strategy has changed from using 'mike deploy' (which manages versioned documentation) to 'peaceiris/actions-gh-pages' (which deploys to specific directories). This breaks the versioning system configured in mkdocs.yml (line 25: 'version.provider: mike'). The mike tool maintains version aliases like 'latest' and handles version switching in the documentation UI, which will no longer work with this approach. For release docs, the new approach deploys to the tag name directory but doesn't set the 'latest' alias that was previously configured.
There was a problem hiding this comment.
@copilot let's update mkdocs.yml such that it do not rely on mike and drop it from requirements
| deploy: | ||
| name: Publish Docs | ||
| runs-on: ubuntu-latest | ||
| timeout-minutes: 10 | ||
| strategy: | ||
| matrix: | ||
| python-version: ["3.10"] | ||
| needs: build-docs |
There was a problem hiding this comment.
The deploy job no longer configures git user credentials (previously set to "github-actions[bot]"), but the peaceiris/actions-gh-pages action handles this internally. However, the job still requires 'contents: write' permission (line 18), but the deploy job itself doesn't explicitly declare this permission in its job-level permissions. The job-level permissions (lines 24-26) only include 'contents: read'. This will cause the deployment to fail as it needs write access to push to the gh-pages branch.
|
@copilot can |
Description
This pull request refactors the documentation build process in GitHub Actions by introducing a reusable workflow,
.github/workflows/build-docs.yml, and updating the existing workflows to use it. This change centralizes and streamlines the logic for building documentation, reduces duplication, and makes it easier to manage updates in one place.Reusable workflow introduction and adoption:
build-docs.yml, which handles building documentation with configurable Python version and support for MkDocs Material Insiders via GitHub App authentication. (.github/workflows/build-docs.yml)publish-docs.ymlto use the new reusablebuild-docs.ymlworkflow for the documentation build step, removing duplicated logic and simplifying the deploy job. (.github/workflows/publish-docs.yml)test-doc.ymlto use the new reusable workflow for testing the documentation build, eliminating redundant steps and configuration. (.github/workflows/test-doc.yml)How has this change been tested, please provide a testcase or example of how you tested the change?
none
Any specific deployment considerations
For example, documentation changes, usability, usage/costs, secrets, etc.