- Notifications
You must be signed in to change notification settings - Fork1k
docs: add a new github action that automatically adds a docs preview#17282
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Closed
Uh oh!
There was an error while loading.Please reload this page.
Closed
Changes fromall commits
Commits
Show all changes
18 commits Select commitHold shift + click to select a range
89ac7c1 new docs preview action
EdwardAngertec2b3bd enhance: implement GitHub Actions best practices for docs-preview-lin…
EdwardAngert57cec51 feat: add docs-analysis composite action
EdwardAngerte26a937 enhance: improve docs-analysis composite action with best practices
EdwardAngerta4d3d94 feat: integrate docs-analysis with docs-preview-link workflow
EdwardAngertea54314 feat: enhance docs-analysis action security and error handling
EdwardAngert2e5d26d feat: enhance docs-ci workflow with security and metrics
EdwardAngert69515e6 fix: resolve YAML formatting issues in docs-analysis action
EdwardAngert13d9d7d chore: add analyze_docs.py script for docs analysis
EdwardAngert7d62132 fix: resolve duplicate step ID in docs-analysis action
EdwardAngert7e150f2 fix: relax branch name validation in docs-analysis action
EdwardAngerte5fa379 fix: resolve regex syntax error in branch validation
EdwardAngert721f4f0 attempt to fix yaml issue
EdwardAngertb0f4315 attempt to fix yaml issue
EdwardAngert6b4f62c fix: use proper variable expansion in Bash here-docs for Markdown links
EdwardAngert5b7ef4f Merge branch 'main' into docs-preview-action
EdwardAngertd8ec639 fix: force GitHub Actions to use latest version of docs-analysis action
EdwardAngert4c93df1 fix: simplify docs-preview workflow (#17292)
EdwardAngertFile filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Jump to file
Failed to load files.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
140 changes: 140 additions & 0 deletions.github/actions/docs-analysis/INTEGRATION.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,140 @@ | ||
| # Integrating with docs-preview-link Workflow | ||
| This guide shows how to integrate the `docs-analysis` composite action with the existing `docs-preview-link.yml` workflow, eliminating duplication and consolidating documentation processing. | ||
| ## Current State | ||
| The docs-preview-link.yml workflow currently embeds document analysis functionality directly in the workflow steps, which leads to: | ||
| - Code duplication across workflows | ||
| - Harder maintenance when metrics need to be updated | ||
| - Inconsistent reporting between workflows | ||
| ## Integration Strategy | ||
| We can refactor the `docs-preview-link.yml` workflow to use our new composite action, bringing these benefits: | ||
| - Single source of truth for document analysis | ||
| - Consistent metrics across all documentation workflows | ||
| - Easier maintenance and feature additions | ||
| - Improved security and error handling | ||
| ## Example Integration | ||
| Here's how to replace the verify-docs-changes job in the docs-preview-link.yml workflow with our composite action: | ||
| ```yaml | ||
| verify-docs-changes: | ||
| needs: [validate-workflow, delay-start] | ||
| runs-on: ubuntu-latest | ||
| timeout-minutes: 3 # Reduced timeout for verification step | ||
| if: | | ||
| always() && | ||
| (needs.validate-workflow.result == 'success' || needs.validate-workflow.result == 'skipped') | ||
| permissions: | ||
| contents: read | ||
| pull-requests: read | ||
| checks: write # For creating check runs | ||
| statuses: write # For creating commit statuses | ||
| if: | | ||
| always() && ( | ||
| (github.event_name == 'pull_request_target' && | ||
| (github.event.pull_request.draft == false || contains(github.event.pull_request.labels.*.name, 'run-checks-on-draft'))) || | ||
| (github.event_name == 'workflow_dispatch') || | ||
| (github.event_name == 'issue_comment' && github.event.issue.pull_request && | ||
| (contains(github.event.comment.body, '/docs-preview') || contains(github.event.comment.body, '/docs-help'))) | ||
| ) | ||
| outputs: | ||
| docs_changed: ${{ steps.docs-analysis.outputs.docs-changed }} | ||
| pr_number: ${{ steps.pr_info.outputs.pr_number }} | ||
| branch_name: ${{ steps.pr_info.outputs.branch_name }} | ||
| repo_owner: ${{ steps.pr_info.outputs.repo_owner }} | ||
| is_fork: ${{ steps.pr_info.outputs.is_fork }} | ||
| is_comment: ${{ steps.pr_info.outputs.is_comment }} | ||
| is_manual: ${{ steps.pr_info.outputs.is_manual }} | ||
| skip: ${{ steps.pr_info.outputs.skip }} | ||
| execution_start_time: ${{ steps.timing.outputs.start_time }} | ||
| has_non_docs_changes: ${{ steps.docs-analysis.outputs.has-non-docs-changes }} | ||
| words_added: ${{ steps.docs-analysis.outputs.words-added }} | ||
| words_removed: ${{ steps.docs-analysis.outputs.words-removed }} | ||
| docs_files_count: ${{ steps.docs-analysis.outputs.docs-files-count }} | ||
| images_added: ${{ steps.docs-analysis.outputs.images-added }} | ||
| manifest_changed: ${{ steps.docs-analysis.outputs.manifest-changed }} | ||
| format_only: ${{ steps.docs-analysis.outputs.format-only }} | ||
| steps: | ||
| # Start timing the execution for performance tracking | ||
| - name: Capture start time | ||
| id: timing | ||
| run: | | ||
| echo "start_time=$(date +%s)" >> $GITHUB_OUTPUT | ||
| echo "::notice::Starting docs preview workflow at $(date)" | ||
| # Apply security hardening to the runner | ||
| - name: Harden Runner | ||
| uses: step-security/harden-runner@latest | ||
| with: | ||
| egress-policy: audit | ||
| - name: Create verification check run | ||
| id: create_check | ||
| uses: actions/github-script@latest | ||
| with: | ||
| github-token: ${{ secrets.GITHUB_TOKEN }} | ||
| script: | | ||
| // [existing script code...] | ||
| - name: Get PR info | ||
| id: pr_info | ||
| run: | | ||
| # [existing script code to get PR number, branch, etc.] | ||
| # Only check out the DEFAULT branch (not the PR code) to verify changes safely | ||
| - name: Check out base repository code | ||
| if: steps.pr_info.outputs.skip != 'true' | ||
| uses: actions/checkout@latest | ||
| with: | ||
| ref: main # Always use the main branch | ||
| fetch-depth: 5 # Reduce checkout depth for faster runs | ||
| sparse-checkout: | | ||
| ${{ env.DOCS_PRIMARY_PATH }} | ||
| *.md | ||
| README.md | ||
| sparse-checkout-cone-mode: false | ||
| # NEW: Use our composite action instead of duplicate logic | ||
| - name: Analyze documentation changes | ||
| id: docs-analysis | ||
| if: steps.pr_info.outputs.skip != 'true' | ||
| uses: ./.github/actions/docs-analysis | ||
| with: | ||
| docs-path: ${{ env.DOCS_PRIMARY_PATH }} | ||
| pr-ref: ${{ steps.pr_info.outputs.branch_name }} | ||
| base-ref: 'main' | ||
| significant-words-threshold: ${{ env.SIGNIFICANT_WORDS_THRESHOLD }} | ||
| throttle-large-repos: 'true' | ||
| debug-mode: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug == 'true' || 'false' }} | ||
| # Remaining steps can use the outputs from docs-analysis | ||
| - name: Update verification status | ||
| if: github.event_name == 'pull_request_target' || (github.event_name == 'workflow_dispatch' && steps.pr_info.outputs.skip != 'true') | ||
| uses: actions/github-script@latest | ||
| with: | ||
| github-token: ${{ secrets.GITHUB_TOKEN }} | ||
| script: | | ||
| // [script modified to use step.docs-analysis outputs] | ||
| ``` | ||
| ## Benefits of Integration | ||
| 1. **Reduced Duplication**: The core document analysis logic is maintained in one place | ||
| 2. **Consistent Features**: All documentation workflows get the same analysis capabilities | ||
| 3. **Better Versioning**: Can pin to specific versions of the docs-analysis action | ||
| 4. **Cleaner Workflow Files**: Simplified workflow YAML with better separation of concerns | ||
| 5. **Improved Maintenance**: Changes to analysis logic only need to be made in one place | ||
| 6. **Common Security Model**: Same input validation and security practices across workflows | ||
| ## Implementation Plan | ||
| 1. Create a small PR with the composite action (completed) | ||
| 2. Test the action in isolation on sample PRs | ||
| 3. Create a new PR that refactors docs-preview-link.yml to use the composite action | ||
| 4. Refactor any other documentation workflows to use the same action | ||
| 5. Establish a process for maintaining the shared action |
252 changes: 252 additions & 0 deletions.github/actions/docs-analysis/README.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,252 @@ | ||
| # Docs Analysis Action | ||
| A composite GitHub Action to analyze documentation changes in pull requests and provide useful metrics and insights. | ||
| ## Features | ||
| - Detects documentation files changed in a PR | ||
| - Calculates metrics (files changed, words added/removed) | ||
| - Tracks image modifications with detailed reporting | ||
| - Analyzes document structure (headings, titles) | ||
| - Identifies the most significantly changed files | ||
| - Integrates with other doc workflows (weekly checks, PR previews) | ||
| - Provides standardized outputs that can be used by any workflow | ||
| ## Usage | ||
| This action analyzes documentation changes to help provide better context and metrics for documentation PRs. | ||
| It only runs on PRs that modify files in the docs directory or markdown files elsewhere in the repo. | ||
| ### Basic Example | ||
| ```yaml | ||
| - name: Analyze Documentation Changes | ||
| uses: ./.github/actions/docs-analysis | ||
| id: docs-analysis | ||
| with: | ||
| docs-path: 'docs/' | ||
| pr-ref: ${{ github.event.pull_request.head.ref }} | ||
| base-ref: 'main' | ||
| ``` | ||
| ### Integration with tj-actions/changed-files (Recommended) | ||
| For optimal performance and reliability, we recommend using with `tj-actions/changed-files`: | ||
| ```yaml | ||
| - uses: tj-actions/changed-files@v45 | ||
| id: changed-files | ||
| with: | ||
| files: | | ||
| docs/** | ||
| **.md | ||
| separator: "," | ||
| - name: Analyze Documentation Changes | ||
| id: docs-analysis | ||
| uses: ./.github/actions/docs-analysis | ||
| with: | ||
| docs-path: 'docs/' | ||
| changed-files: ${{ steps.changed-files.outputs.all_changed_files }} | ||
| files-pattern: 'docs/**|**.md' | ||
| ``` | ||
| ### Complete Example with Conditionals | ||
| ```yaml | ||
| jobs: | ||
| check-docs-changes: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout code | ||
| uses: actions/checkout@v3 | ||
| with: | ||
| fetch-depth: 0 | ||
| - uses: tj-actions/changed-files@v45 | ||
| id: changed-files | ||
| with: | ||
| files: | | ||
| docs/** | ||
| **.md | ||
| separator: "," | ||
| - name: Analyze Documentation Changes | ||
| uses: ./.github/actions/docs-analysis | ||
| id: docs-analysis | ||
| with: | ||
| docs-path: 'docs/' | ||
| changed-files: ${{ steps.changed-files.outputs.all_changed_files }} | ||
| significant-words-threshold: '100' | ||
| skip-if-no-docs: 'true' | ||
| debug-mode: 'false' | ||
| - name: Create Preview Comment | ||
| if: steps.docs-analysis.outputs.docs-changed == 'true' | ||
| run: | | ||
| echo "Found ${{ steps.docs-analysis.outputs.docs-files-count }} changed docs files" | ||
| echo "Words: +${{ steps.docs-analysis.outputs.words-added }}/-${{ steps.docs-analysis.outputs.words-removed }}" | ||
| if [[ "${{ steps.docs-analysis.outputs.images-total }}" != "0" ]]; then | ||
| echo "Images changed: ${{ steps.docs-analysis.outputs.images-total }}" | ||
| fi | ||
| if [[ "${{ steps.docs-analysis.outputs.significant-change }}" == "true" ]]; then | ||
| echo "This is a significant docs change!" | ||
| fi | ||
| ``` | ||
| ## Inputs | ||
| | Name | Description | Required | Default | | ||
| |------|-------------|----------|---------| | ||
| | `docs-path` | Path to the documentation directory | No | `docs/` | | ||
| | `files-pattern` | Glob pattern(s) for documentation files (use vertical bar \| to separate multiple patterns) | No | `**.md\|docs/**` | | ||
| | `changed-files` | Comma-separated list of changed files (from tj-actions/changed-files) | No | `` | | ||
| | `pr-ref` | PR reference to analyze | No | `github.event.pull_request.head.ref` | | ||
| | `base-ref` | Base reference to compare against | No | `main` | | ||
| | `files-changed` | Comma-separated list of files changed (legacy input, use `changed-files` instead) | No | `` | | ||
| | `max-scan-files` | Maximum number of files to scan | No | `100` | | ||
| | `max-files-to-analyze` | Maximum files to analyze in detail (for performance) | No | `20` | | ||
| | `throttle-large-repos` | Enable throttling for large repositories | No | `true` | | ||
| | `significant-words-threshold` | Threshold for significant text changes | No | `100` | | ||
| | `skip-if-no-docs` | Whether to skip if no docs files are changed | No | `true` | | ||
| | `debug-mode` | Enable verbose debugging output | No | `false` | | ||
| | `use-changed-files-action` | Whether to use tj-actions/changed-files instead of git commands | No | `false` | | ||
| ## Outputs | ||
| | Name | Description | | ||
| |------|-------------| | ||
| | `docs-changed` | Whether documentation files were changed (`true`/`false`) | | ||
| | `docs-files-count` | Number of documentation files changed | | ||
| | `words-added` | Number of words added to documentation | | ||
| | `words-removed` | Number of words removed from documentation | | ||
| | `images-added` | Number of images added | | ||
| | `images-modified` | Number of images modified | | ||
| | `images-deleted` | Number of images deleted | | ||
| | `images-total` | Total number of images changed | | ||
| | `image-names` | Comma-separated list of changed image files | | ||
| | `manifest-changed` | Whether manifest.json was changed (`true`/`false`) | | ||
| | `format-only` | Whether changes are formatting-only (`true`/`false`) | | ||
| | `significant-change` | Whether changes are significant (`true`/`false`) | | ||
| | `has-non-docs-changes` | Whether PR contains non-docs changes (`true`/`false`) | | ||
| | `most-changed-file` | Path to the most changed file | | ||
| | `most-changed-url-path` | URL path for the most changed file | | ||
| | `most-significant-image` | Path to the most significant image | | ||
| | `doc-structure` | JSON structure of document heading counts | | ||
| | `execution-time` | Execution time in seconds | | ||
| | `cache-key` | Cache key for this analysis run | | ||
| ## Security Features | ||
| - Stronger input validation with whitelist approach for branch references | ||
| - Enhanced path sanitization with traversal detection | ||
| - Secure command execution (no eval) in git retry operations | ||
| - Error tracing with line numbers for better debugging | ||
| - Cross-platform compatibility with fallbacks | ||
| - Repository size detection with adaptive throttling | ||
| - Python integration for safer JSON handling (with bash fallbacks) | ||
| - Performance monitoring with execution metrics | ||
| ## Performance Optimization | ||
| - Configurable document scan limits | ||
| - Intelligent throttling for large repositories | ||
| - Git performance tuning | ||
| - Execution time tracking | ||
| - Content-based caching | ||
| - Debug mode for troubleshooting | ||
| ## Examples | ||
| ### Analyzing Documentation Changes for a PR | ||
| ```yaml | ||
| - name: Analyze Documentation Changes | ||
| uses: ./.github/actions/docs-analysis | ||
| id: docs-analysis | ||
| with: | ||
| docs-path: 'docs/' | ||
| ``` | ||
| ### Analyzing Non-Git Files | ||
| ```yaml | ||
| - name: Analyze Documentation Files | ||
| uses: ./.github/actions/docs-analysis | ||
| id: docs-analysis | ||
| with: | ||
| files-changed: 'docs/file1.md,docs/file2.md,README.md' | ||
| docs-path: 'docs/' | ||
| ``` | ||
| ### Debug Mode for Troubleshooting | ||
| ```yaml | ||
| - name: Analyze Documentation with Debug Output | ||
| uses: ./.github/actions/docs-analysis | ||
| id: docs-analysis | ||
| with: | ||
| docs-path: 'docs/' | ||
| debug-mode: 'true' | ||
| ``` | ||
| ## Unified Documentation Workflows | ||
| This action is designed to work seamlessly with Coder's other documentation-related workflows: | ||
| ### How to Use with docs-ci.yaml | ||
| The `docs-ci.yaml` workflow uses this action to analyze documentation changes for linting and formatting: | ||
| ```yaml | ||
| # From .github/workflows/docs-ci.yaml | ||
| - uses: tj-actions/changed-files@v45 | ||
| id: changed-files | ||
| with: | ||
| files: | | ||
| docs/** | ||
| **.md | ||
| separator: "," | ||
| - name: Analyze documentation changes | ||
| id: docs-analysis | ||
| uses: ./.github/actions/docs-analysis | ||
| with: | ||
| docs-path: "docs/" | ||
| changed-files: ${{ steps.changed-files.outputs.all_changed_files }} | ||
| files-pattern: "docs/**|**.md" | ||
| ``` | ||
| ### How to Use with docs-preview-link.yml | ||
| This action can be used in the `docs-preview-link.yml` workflow to analyze documentation changes for preview generation: | ||
| ```yaml | ||
| # Example integration with docs-preview-link.yml | ||
| - name: Analyze documentation changes | ||
| id: docs-analysis | ||
| uses: ./.github/actions/docs-analysis | ||
| with: | ||
| docs-path: "docs/" | ||
| pr-ref: ${{ steps.pr_info.outputs.branch_name }} | ||
| base-ref: 'main' | ||
| ``` | ||
| ### How to Use with weekly-docs.yaml | ||
| This action can be used to enhance the weekly documentation checks: | ||
| ```yaml | ||
| # Example integration with weekly-docs.yaml | ||
| - name: Analyze documentation structure | ||
| id: docs-analysis | ||
| uses: ./.github/actions/docs-analysis | ||
| with: | ||
| docs-path: "docs/" | ||
| files-pattern: "docs/**" | ||
| max-scan-files: "500" # Higher limit for full repo scan | ||
| ``` | ||
| By using this shared action across all documentation workflows, you ensure consistent analysis, metrics, and reporting for all documentation-related tasks. |
Oops, something went wrong.
Uh oh!
There was an error while loading.Please reload this page.
Oops, something went wrong.
Uh oh!
There was an error while loading.Please reload this page.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.