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.

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

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

Here's how to replace the verify-docs-changes job in the docs-preview-link.yml workflow with our composite action:

verify-docs-changes:

needs: [validate-workflow, delay-start]

runs-on: ubuntu-latest

timeout-minutes: 3 # Reduced timeout for verification step

if: |

permissions:

contents: read

pull-requests: read

checks: write # For creating check runs

statuses: write # For creating commit statuses

if: |

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: |

# 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: |

- name: Get PR info

id: pr_info

run: |

# 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: |

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: |

files-pattern:

description: 'Glob pattern(s) for documentation files (use vertical bar | to separate multiple patterns)'

required: false

default: '**.md|docs/**'

changed-files:

description: 'Comma-separated list of changed files (from tj-actions/changed-files)'

required: false

default: ''

use-changed-files-action:

description: 'Whether to use tj-actions/changed-files instead of git commands'

required: false

default: 'false'

manifest-changed-files:

description: 'List of files referenced in manifest changes'

value: ${{ steps.verify.outputs.manifest_changed_files }}

image-focused:

description: 'Whether changes are focused on images'

value: ${{ steps.verify.outputs.image_focused }}

changed-docs-files:

description: 'List of changed docs files'

value: ${{ steps.verify.outputs.changed_docs_files }}

docs-dir-files:

description: 'List of changed files in docs directory'

value: ${{ steps.verify.outputs.docs_dir_files }}