|
| 1 | +# Docs Shared Action |
| 2 | + |
| 3 | +A composite GitHub action that provides shared functionality for docs-related workflows. This action unifies the common patterns across documentation linting, formatting, preview link generation, and PR commenting. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- Detects changes in documentation files using `tj-actions/changed-files` |
| 8 | +- Provides linting and formatting for markdown files |
| 9 | +- Generates preview links for documentation changes |
| 10 | +- Creates or updates PR comments with preview links |
| 11 | +- Handles special analysis of manifest.json changes |
| 12 | +- Includes security hardening measures |
| 13 | +- Provides detailed outputs for use in workflows |
| 14 | + |
| 15 | +## Security Features |
| 16 | + |
| 17 | +- Uses secure file permissions with `umask 077` |
| 18 | +- Clears potentially harmful environment variables |
| 19 | +- Input validation and sanitization |
| 20 | +- Can work with harden-runner actions |
| 21 | + |
| 22 | +## Usage |
| 23 | + |
| 24 | +```yaml |
| 25 | +- name: Process Documentation |
| 26 | + id: docs-shared |
| 27 | + uses: ./.github/actions/docs-shared |
| 28 | + with: |
| 29 | + github-token: ${{ secrets.GITHUB_TOKEN }} |
| 30 | + docs-dir: docs |
| 31 | + include-md-files: "true" |
| 32 | + check-links: "true" |
| 33 | + lint-markdown: "true" |
| 34 | + format-markdown: "true" |
| 35 | + generate-preview: "true" |
| 36 | + post-comment: "true" |
| 37 | + pr-number: "${{ github.event.pull_request.number }}" |
| 38 | + fail-on-error: "true" |
| 39 | +``` |
| 40 | +
|
| 41 | +## Inputs |
| 42 | +
|
| 43 | +| Input | Description | Required | Default | |
| 44 | +|------------------|-----------------------------------------------------|----------|---------| |
| 45 | +| github-token | GitHub token for API operations | Yes | - | |
| 46 | +| docs-dir | Path to the docs directory | No | docs | |
| 47 | +| include-md-files | Whether to include all markdown files (not just docs) | No | false | |
| 48 | +| check-links | Whether to check links in markdown files | No | false | |
| 49 | +| lint-markdown | Whether to lint markdown files | No | false | |
| 50 | +| format-markdown | Whether to check markdown formatting | No | false | |
| 51 | +| generate-preview | Whether to generate preview links | No | false | |
| 52 | +| post-comment | Whether to post a PR comment with results | No | false | |
| 53 | +| pr-number | PR number for commenting | No | "" | |
| 54 | +| fail-on-error | Whether to fail the workflow on errors | No | true | |
| 55 | +
|
| 56 | +## Outputs |
| 57 | +
|
| 58 | +| Output | Description | |
| 59 | +|-----------------------|---------------------------------------------------| |
| 60 | +| has_changes | Boolean indicating if documentation files changed | |
| 61 | +| changed_files | JSON array of changed documentation files | |
| 62 | +| formatted_changed_files | Markdown-formatted list of changed files with links | |
| 63 | +| preview_url | Documentation preview URL | |
| 64 | +| manifest_changed | Boolean indicating if manifest.json changed | |
| 65 | +| has_new_docs | Boolean indicating if new docs were added | |
| 66 | +| new_docs | List of newly added docs formatted for comment | |
| 67 | +| preview_links | List of preview links for newly added docs | |
| 68 | +| lint_results | Results from linting | |
| 69 | +| format_results | Results from format checking | |
| 70 | +| link_check_results | Results from link checking | |
| 71 | +
|
| 72 | +## Example |
| 73 | +
|
| 74 | +See the [docs-shared-example.yaml](./.github/workflows/docs-shared-example.yaml) workflow for a complete example of how to use this action. |
0 commit comments