docs: publish the developer documentation as a site #1
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| name: "Docs" | ||
|
|
||
| # Deliberately separate from main.yml. The Python suite must not gate a typo fix in | ||
| # the documentation, and a broken MDX page must not gate a release — they are | ||
| # different artifacts with different reviewers and very different run times. | ||
| on: | ||
| push: | ||
| paths: | ||
| - 'docs/site/**' | ||
| - '.github/workflows/docs.yml' | ||
| pull_request: | ||
| paths: | ||
| - 'docs/site/**' | ||
| - '.github/workflows/docs.yml' | ||
| workflow_dispatch: | ||
|
|
||
| # GitHub Pages needs these on the deploy job. `contents: read` is the default for | ||
| # the rest; nothing here writes to the repository. | ||
| permissions: | ||
| contents: read | ||
|
|
||
| # One deploy at a time, and never cancel one in flight: a cancelled deploy-pages run | ||
| # can leave the Pages site pointing at a half-uploaded artifact. | ||
| concurrency: | ||
| group: "pages" | ||
| cancel-in-progress: false | ||
|
|
||
| defaults: | ||
| run: | ||
| working-directory: docs/site | ||
|
|
||
| jobs: | ||
|
|
||
| build: | ||
| name: "Docs: Build" | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v5 | ||
|
Comment on lines
+38
to
+39
There was a problem hiding this comment. 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🌐 Web query:
💡 Result: Yes, actions/checkout@v5 supports the persist-credentials: false input [1][2]. Setting persist-credentials: false prevents the action from configuring your repository's Git authentication credentials (such as the GITHUB_TOKEN) in the runner's Git configuration [1][3]. By default, this input is true, which causes the action to persist these credentials to allow subsequent Git operations to run automatically authenticated [1][3]. When you set persist-credentials: false, the action skips the step of writing these credentials to the Git configuration entirely, thereby preventing them from being stored on the disk [3]. In versions like v5, even when enabled, the credentials are no longer stored directly in the local.git/config file but rather in a separate file (typically in $RUNNER_TEMP), though opting out remains the most secure practice to avoid unnecessary credential exposure [4][3]. Citations:
🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- workflow ---'
sed -n '1,120p' .github/workflows/docs.yml
printf '%s\n' '--- checkout references ---'
rg -n -C 3 'actions/checkout|npm ci|pull_request|permissions|persist-credentials' .github/workflows/docs.yml .github/workflows 2>/dev/null || trueRepository: IMIO/imio.emailkit Length of output: 10248 Disable persisted checkout credentials. For 🧰 Tools🪛 zizmor (1.28.0)[warning] 38-39: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false (artipacked) 🤖 Prompt for AI AgentsSource: Linters/SAST tools |
||
|
|
||
| - name: Set up Node | ||
| uses: actions/setup-node@v4 | ||
| with: | ||
| node-version: '22' | ||
| cache: 'npm' | ||
| cache-dependency-path: docs/site/package-lock.json | ||
|
|
||
| - name: Install dependencies | ||
| run: npm ci | ||
|
|
||
| - name: Lint | ||
| run: npm run lint | ||
|
|
||
| - name: Build the static site | ||
| # The site is served from https://<owner>.github.io/<repo>/, so every asset | ||
| # and link needs a /<repo> prefix. Reading it from the repository name rather | ||
| # than hardcoding it means a fork builds correctly with no edit. | ||
| env: | ||
| NEXT_BASE_PATH: /${{ github.event.repository.name }} | ||
| run: npm run build | ||
|
|
||
| - name: Upload the Pages artifact | ||
| uses: actions/upload-pages-artifact@v3 | ||
| with: | ||
| path: docs/site/out | ||
|
|
||
| deploy: | ||
| name: "Docs: Deploy to GitHub Pages" | ||
| # Only the default branch publishes. Every other push and every pull request | ||
| # still runs `build` above, so a page that fails to render is caught before merge. | ||
| if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' | ||
| needs: build | ||
| runs-on: ubuntu-latest | ||
| permissions: | ||
| pages: write | ||
| id-token: write | ||
| environment: | ||
| name: github-pages | ||
| url: ${{ steps.deployment.outputs.page_url }} | ||
| steps: | ||
| - name: Deploy | ||
| id: deployment | ||
| uses: actions/deploy-pages@v4 | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Include
.gitignorein both path filters.The documentation build previously depended on root
.gitignorebehavior. A.gitignore-only change can break the documentation build without starting this workflow. Add.gitignoreto thepush.pathsandpull_request.pathslists.🤖 Prompt for AI Agents