Doc Detective Install Github Action

Install GitHub Action

Skill: doc-detective:install-github-action

Install and configure the Doc Detective GitHub Action for automated documentation testing in CI. Detects project context, creates the workflow file, and configures optional features like PR creation and issue creation.

Usage

/doc-detective-install-github-action [options]

/doc-detective-install-github-action
/doc-detective-install-github-action --ci
/doc-detective-install-github-action --trigger push --exit-on-fail
/doc-detective-install-github-action --create-pr-on-change --create-issue-on-fail --integrations claude,copilot

Entry Criteria

Confirm all of the following before starting. If any item is unavailable, stop and ask the user.

Exit Criteria

Before completing:

1. Workflow YAML file created at .github/workflows/doc-detective.yml (or user-chosen name)
2. Required permissions correctly set in the permissions: block
3. Optional features (PR creation, issue creation, integrations) configured per user choices
4. Manual steps reported to user (e.g., enabling Actions permissions, adding secrets)

Workflow

Phases run in order. Do NOT advance to the next phase if the current phase fails.

1. Detect → 2. Configure → 3. Write → 4. Report

Phase 1: Detect Context

1. Confirm this is a Git repository (.git exists as a file or directory). If not, stop and inform the user.
2. Confirm the remote points to GitHub. Check .git/config for github.com in a remote URL, or run gh repo view --json url if the gh CLI is available. If not a GitHub repo, stop and inform the user this skill is GitHub-specific.
3. Check for existing Doc Detective config: .doc-detective.json, doc-detective.config.js. Record the path if found.
4. Check for existing workflows in .github/workflows/ — note any existing doc-detective*.yml files to avoid conflicts.
5. Identify the docs directory: use the input field from existing config if available, otherwise look for common directories (docs/, documentation/, content/, wiki/). Fall back to . if no convention is detected.

Phase 2: Configure Workflow

Build the workflow YAML based on project context and user options.

Base workflow structure:

name: Doc Detective

on:
  <trigger>:     # from --trigger option, default: pull_request

permissions:
  contents: read   # base permission; expanded below if features require it

jobs:
  doc-detective:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: doc-detective/github-action@v1
        with:
          # Inputs configured per options

Configuration rules:

If not in --ci mode, present the generated workflow to the user for confirmation before writing. Explain each enabled feature and the permissions it requires.

Phase 3: Write Workflow

1. Create .github/workflows/ directory if it doesn't exist.
2. Check if .github/workflows/doc-detective.yml already exists.
   • If it exists and not in --ci mode: show the existing file, ask the user for an alternative name or confirm overwrite.
   • If it exists and in --ci mode: use doc-detective-<timestamp>.yml to avoid overwriting.
3. Write the workflow YAML file.

Phase 4: Report

Summarize what was created and list any manual steps needed:

• Created: Path to the workflow file and a summary of configured features.
• Manual steps (if applicable):
  • If --create-pr-on-change: Remind the user that the default GITHUB_TOKEN works for PR creation, but if the repo requires specific token permissions, they may need to configure a custom token.
  • If using a custom token input: Remind the user to add the secret to the repository settings.
  • If the repository has branch protection rules: Note that PRs created by the action use the default GITHUB_TOKEN and may need approval before merging.
  • General: Confirm that GitHub Actions is enabled for the repository.

Examples

Basic — test on pull requests

name: Doc Detective

on:
  pull_request:

permissions:
  contents: read

jobs:
  doc-detective:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: doc-detective/github-action@v1

With PR creation on file changes

name: Doc Detective

on:
  pull_request:

permissions:
  contents: write
  pull-requests: write

jobs:
  doc-detective:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: doc-detective/github-action@v1
        with:
          exit_on_fail: true
          create_pr_on_change: true

With issue creation and integrations

name: Doc Detective

on:
  push:
    branches: [main]

permissions:
  contents: read
  issues: write

jobs:
  doc-detective:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: doc-detective/github-action@v1
        with:
          exit_on_fail: true
          create_issue_on_fail: true
          integrations: claude,copilot

Full-featured with custom config

name: Doc Detective

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  doc-detective:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: doc-detective/github-action@v1
        with:
          config: docs/.doc-detective.json
          exit_on_fail: true
          create_pr_on_change: true
          pr_labels: doc-detective,automated
          create_issue_on_fail: true
          issue_labels: doc-detective,test-failure
          integrations: claude,copilot

Related Commands

• /doc-detective-init — Initialize Doc Detective in a repository (includes GitHub Action setup as final step)
• /doc-detective-project-bootstrap — Full project bootstrap (includes GitHub Action setup as final step)
• /doc-detective-test — Run existing Doc Detective tests