Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

docs: add shared docs GitHub action for workflow efficiency#17322

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
EdwardAngert wants to merge8 commits intomainfromdocs-shared-action
Closed
Show file tree
Hide file tree
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 192 additions & 0 deletions.github/actions/docs-preview/action.yaml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
name: 'Docs Preview Action'
description: 'A composite action to provide Vercel preview links for documentation changes'
author: 'Coder'
inputs:
github-token:
description: 'GitHub token for API operations'
required: true
docs-dir:
description: 'Path to the docs directory'
required: false
default: 'docs'
vercel-domain:
description: 'DEPRECATED - Previously for Vercel, now using different URL format'
required: false
default: 'coder-docs-git'
changed-files:
description: 'JSON string of changed files (from tj-actions/changed-files)'
required: true
manifest-changed:
description: 'Boolean indicating if manifest.json has changed (from tj-actions/changed-files)'
required: true

outputs:
has_changes:
description: 'Boolean indicating if documentation files have changed'
value: ${{ steps.docs-analysis.outputs.has_changes }}
changed_files:
description: 'List of changed documentation files formatted for comment'
value: ${{ steps.docs-analysis.outputs.changed_files }}
url:
description: 'Vercel preview URL'
value: ${{ steps.vercel-preview.outputs.url }}
has_new_docs:
description: 'Boolean indicating if new docs were added in manifest.json'
value: ${{ steps.manifest-analysis.outputs.has_new_docs || 'false' }}
new_docs:
description: 'List of newly added docs formatted for comment'
value: ${{ steps.manifest-analysis.outputs.new_docs || '' }}
preview_links:
description: 'List of preview links for newly added docs'
value: ${{ steps.manifest-analysis.outputs.preview_links || '' }}

runs:
using: 'composite'
steps:
- name: Set security environment
shell: bash
run: |
# Secure the environment by clearing potentially harmful variables
unset HISTFILE
umask 077

# Validate that docs directory exists
if [ ! -d "${{ inputs.docs-dir }}" ]; then
echo "::error::Docs directory '${{ inputs.docs-dir }}' does not exist"
exit 1
fi

- name: Debug inputs
shell: bash
run: |
echo "Docs dir: ${{ inputs.docs-dir }}"
echo "Manifest changed: ${{ inputs.manifest-changed }}"
echo "First few changed files:"
echo '${{ inputs.changed-files }}' | jq -r '.[] | select(startswith("${{ inputs.docs-dir }}/"))' | head -n 5

- name: Analyze docs changes
id: docs-analysis
shell: bash
run: |
# Parse changed files from input and write to temp file with strict permissions
echo '${{ inputs.changed-files }}' > changed_files.json

# Count total changed doc files
DOC_FILES_COUNT=$(jq -r '.[] | select(startswith("${{ inputs.docs-dir }}/"))' changed_files.json | wc -l)
echo "doc_files_count=$DOC_FILES_COUNT" >> $GITHUB_OUTPUT

# Force to true for debugging
DOC_FILES_COUNT=1

# Get branch name for URLs
BRANCH_NAME=$(jq --raw-output .pull_request.head.ref "$GITHUB_EVENT_PATH")

# Format changed files for comment with clickable links
FORMATTED_FILES=""
while read -r file_path; do
[ -z "$file_path" ] && continue

# Create direct link to file
# Remove .md extension and docs/ prefix for the URL path
url_path=$(echo "$file_path" | sed 's/^docs\///' | sed 's/\.md$//')
file_url="https://coder.com/docs/@${BRANCH_NAME}/${url_path}"

# Add the formatted line with link
FORMATTED_FILES="${FORMATTED_FILES}- [$file_path]($file_url)\n"
done < <(jq -r '.[] | select(startswith("${{ inputs.docs-dir }}/"))' changed_files.json)

# Add a minimum placeholder if no files found
if [ -z "$FORMATTED_FILES" ]; then
# Hardcode a test example that links directly to the parameters.md file
FORMATTED_FILES="- [docs/admin/templates/extending-templates/parameters.md](https://coder.com/docs/@${BRANCH_NAME}/admin/templates/extending-templates/parameters)\n"
fi

echo "changed_files<<EOF" >> $GITHUB_OUTPUT
echo -e "$FORMATTED_FILES" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT

# Determine if docs have changed - force true for testing
echo "has_changes=true" >> $GITHUB_OUTPUT

# Clean up sensitive file
rm -f changed_files.json

- name: Generate Vercel preview URL
id: vercel-preview
if: steps.docs-analysis.outputs.has_changes == 'true'
shell: bash
run: |
# Get PR branch name for Vercel preview URL
BRANCH_NAME=$(jq --raw-output .pull_request.head.ref "$GITHUB_EVENT_PATH")

# Input validation - ensure branch name is valid
if [ -z "$BRANCH_NAME" ]; then
echo "::error::Could not determine branch name"
exit 1
fi

# For debugging
echo "Branch name: $BRANCH_NAME"

# Create the correct Vercel preview URL
VERCEL_PREVIEW_URL="https://coder.com/docs/@$BRANCH_NAME"
echo "url=$VERCEL_PREVIEW_URL" >> $GITHUB_OUTPUT

- name: Analyze manifest changes
id: manifest-analysis
if: inputs.manifest-changed == 'true'
shell: bash
run: |
# Get PR number for links
PR_NUMBER=$(jq --raw-output .pull_request.number "$GITHUB_EVENT_PATH")

# Get the base SHA for diff
BASE_SHA=$(git merge-base HEAD origin/main)

# Extract new docs from manifest.json diff with safe patterns
NEW_DOCS=$(git diff "$BASE_SHA"..HEAD -- "${{ inputs.docs-dir }}/manifest.json" | grep -E '^\+.*"path":' | sed -E 's/.*"path": *"(.*)".*/\1/g')

if [ -n "$NEW_DOCS" ]; then
echo "has_new_docs=true" >> $GITHUB_OUTPUT

# Format new docs for comment
FORMATTED_NEW_DOCS=$(echo "$NEW_DOCS" | sort | uniq | grep -v "^$" | sed 's/^/- `/g' | sed 's/$/`/g')
echo "new_docs<<EOF" >> $GITHUB_OUTPUT
echo "$FORMATTED_NEW_DOCS" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT

# Generate preview links for new docs
PREVIEW_LINKS=""
while IFS= read -r doc_path; do
# Skip empty lines
[ -z "$doc_path" ] && continue

# Clean the path and sanitize
clean_path=${doc_path#./}
clean_path=$(echo "$clean_path" | tr -cd 'a-zA-Z0-9_./-')

# Get branch name for URLs
BRANCH_NAME=$(jq --raw-output .pull_request.head.ref "$GITHUB_EVENT_PATH")

# Generate preview URL with correct format
url_path=$(echo "$clean_path" | sed 's/\.md$//')
preview_url="https://coder.com/docs/@${BRANCH_NAME}/${url_path}"

# Extract doc title or use filename safely
if [ -f "$doc_path" ]; then
title=$(grep -m 1 "^# " "$doc_path" | sed 's/^# //')
title=$(echo "$title" | tr -cd 'a-zA-Z0-9 _.,-')
[ -z "$title" ] && title=$(basename "$doc_path" .md | tr -cd 'a-zA-Z0-9_.-')
else
title=$(basename "$doc_path" .md | tr -cd 'a-zA-Z0-9_.-')
fi

PREVIEW_LINKS="${PREVIEW_LINKS}- [$title]($preview_url)\n"
done <<< "$NEW_DOCS"

echo "preview_links<<EOF" >> $GITHUB_OUTPUT
echo -e "$PREVIEW_LINKS" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
else
echo "has_new_docs=false" >> $GITHUB_OUTPUT
fi
74 changes: 74 additions & 0 deletions.github/actions/docs-shared/README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
# Docs Shared Action

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.

## Features

- Detects changes in documentation files using `tj-actions/changed-files`
- Provides linting and formatting for markdown files
- Generates preview links for documentation changes
- Creates or updates PR comments with preview links
- Handles special analysis of manifest.json changes
- Includes security hardening measures
- Provides detailed outputs for use in workflows

## Security Features

- Uses secure file permissions with `umask 077`
- Clears potentially harmful environment variables
- Input validation and sanitization
- Can work with harden-runner actions

## Usage

```yaml
- name: Process Documentation
id: docs-shared
uses: ./.github/actions/docs-shared
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
docs-dir: docs
include-md-files: "true"
check-links: "true"
lint-markdown: "true"
format-markdown: "true"
generate-preview: "true"
post-comment: "true"
pr-number: "${{ github.event.pull_request.number }}"
fail-on-error: "true"
```

## Inputs

| Input | Description | Required | Default |
|------------------|-----------------------------------------------------|----------|---------|
| github-token | GitHub token for API operations | Yes | - |
| docs-dir | Path to the docs directory | No | docs |
| include-md-files | Whether to include all markdown files (not just docs) | No | false |
| check-links | Whether to check links in markdown files | No | false |
| lint-markdown | Whether to lint markdown files | No | false |
| format-markdown | Whether to check markdown formatting | No | false |
| generate-preview | Whether to generate preview links | No | false |
| post-comment | Whether to post a PR comment with results | No | false |
| pr-number | PR number for commenting | No | "" |
| fail-on-error | Whether to fail the workflow on errors | No | true |

## Outputs

| Output | Description |
|-----------------------|---------------------------------------------------|
| has_changes | Boolean indicating if documentation files changed |
| changed_files | JSON array of changed documentation files |
| formatted_changed_files | Markdown-formatted list of changed files with links |
| preview_url | Documentation preview URL |
| manifest_changed | Boolean indicating if manifest.json changed |
| has_new_docs | Boolean indicating if new docs were added |
| new_docs | List of newly added docs formatted for comment |
| preview_links | List of preview links for newly added docs |
| lint_results | Results from linting |
| format_results | Results from format checking |
| link_check_results | Results from link checking |

## Example

See the [docs-shared-example.yaml](./.github/workflows/docs-shared-example.yaml) workflow for a complete example of how to use this action.
Loading
Loading
[8]ページ先頭
©2009-2025 Movatter.jp