Docs changes workflow

[tbuchaillot]

Jira Ticket

TT-XXXXX

Description

Adds a reusable docs-preview workflow that catches PM feedback on generated documentation at the source-code PR, before the docs are ever synced.

Today, config docs and OAS/API-spec docs in tyk-docs are generated from source repos (Go doc comments, apidef/oas annotations, swagger files) by the exp tyk-docs.yml sync. PMs only see the content once it lands in the generated tyk-docs PR — and since that content can't be edited there, every PM correction means fixing the source repo, re-running the sync, and re-reviewing a new PR.

This workflow closes that loop early: on a PR in a source repo that touches doc-bearing paths, it runs the same generators as the sync against the PR's base and head, and if the rendered output differs, posts the docs diff as a sticky PR comment and requests an advisory review from a configurable PM team. Merges are never blocked, and PMs are never pinged when a change has no documentation impact.

Behavior summary:

• PR doesn't touch configured docs_paths → workflow ends silently.
• Touches them but generated output is identical (pure refactor) → existing preview comment flips to "No documentation impact"; otherwise stays silent.
• Generated output changed → sticky comment with the rendered docs diff (truncated at 60k chars; full diff uploaded as the docs-preview-diff artifact) plus a one-time advisory review request to pm_team.
• Fork PRs are skipped (secrets unavailable; the config generator resolves remote branch names).

Consumer usage (per repo, with repo-specific paths):

jobs:
  docs-preview:
    uses: TykTechnologies/github-actions/.github/workflows/docs-preview.yml@main
    with:
      component: gateway  # gateway | dashboard | pump | mdcb | portal
      docs_paths: |
        apidef/oas/**
        config/**
        swagger.yml
      pm_team: <pm-team-slug>
    secrets: inherit

Generation steps (schema-gen flags, swagger Mintlify massage, tyk-config-info-generator invocation, OAS duplicate cleanup) are copied verbatim from exp's tyk-docs.yml so the preview matches what the sync will later produce. Factoring both into shared composite actions is a planned follow-up.

Type of Change

• Bug fix
• New feature / action
• Refactor / improvement
• Documentation update
• CI/CD / workflow change
• Other (please describe):

Changes Made

• Add .github/workflows/docs-preview.yml reusable workflow (workflow_call) with two jobs:
  • detect: matches PR-changed files against the docs_paths globs; skips fork PRs.
  • preview: generates docs for base and head per component (gateway/dashboard/pump/mdcb/portal), diffs them, uploads the full diff artifact, posts/updates a marker-identified sticky comment, and requests the pm_team review once per PR via the PROBE GitHub App token.
• Add docs/workflows/docs-preview.md (README source documentation).
• Regenerate README.md via task gen. The README was stale, so the diff also picks up "Undocumented action" stubs for workflows added since the last regeneration, and drops Github to slack / PR Agent, whose source files no longer exist.
• Add docs/workflows/s1-cns-scan.md and docs/workflows/release-bot.md: these sections had been hand-edited into README only, so regeneration was silently deleting them — their content is now preserved in the docs/ source of truth.
• Add adoption caller snippets and a rollout runbook for the five target repos (tyk, tyk-analytics, tyk-pump, tyk-sink, portal) under docs/superpowers/plans/2026-07-21-docs-preview-adoption/.

Testing

• Glob matcher (detect job logic) validated with a 7-case local bash harness: nested paths, exact filenames, prefix collisions (config.go vs config/**), empty input, multi-file PRs.
• Comment-body builder validated with a 9-case local harness: sticky marker, team cc present/absent, 60k truncation with artifact link, and diffs containing triple backticks (4-backtick fence).
• task lint (yamllint + README regeneration) passes; docs lint reports no missing documentation for the new workflow.
• Manually triggered the affected workflow(s) and verified expected behaviour — pending pilot: a draft PR in tyk with the caller pinned to this branch (runbook step 2) exercising the three scenarios (docs diff + one-time PM request / "no documentation impact" flip / silent skip).
• Checked that existing workflows are not broken (no existing workflow modified; README changes are generator output).

Checklist

• My changes follow the existing conventions in this repo
• I have updated relevant documentation (e.g. README.md, action description fields)
• For changed shell scripts (if applicable): I ran shellcheck, used an appropriate shebang and error handling, and preserved required executable permissions (n/a — shell logic is inline in workflow YAML; validated via local bash test harnesses instead)
• For changed actions/scripts (if applicable): I added or updated validation, tests, or clear manual verification steps
• For changed JavaScript files (if applicable): I ran the relevant tests and linting/formatting checks
• For changed Python files (if applicable): I ran the relevant tests and linting/formatting checks
• For Dockerfile changes (if applicable): I reviewed the base image, build context, image size, and runtime security
• For changed actions (if applicable): I updated the action.yml interface, defaults, outputs, and examples as needed
• I reviewed security implications, including least-privilege permissions and safe handling of inputs, secrets, and tokens (if applicable)
• For workflow changes (if applicable): I reviewed triggers, permissions, concurrency, and fork safety
• I have assigned a reviewer

[probelabs]

This pull request introduces a new reusable GitHub Actions workflow, docs-preview.yml, designed to generate and display a diff of documentation changes directly within a pull request. This allows for earlier feedback from product managers and other stakeholders, streamlining the review process by catching documentation issues before code is merged.

In addition to the new workflow, this PR includes a significant effort to improve the repository's overall documentation. The main README.md has been substantially updated to document the new workflow and several other existing workflows that were previously undocumented. New, dedicated documentation files have also been added to the docs/workflows/ directory.

Files Changed Analysis

• .github/workflows/docs-preview.yml (New): The core of the PR, this file defines the new reusable workflow. It includes two jobs: detect to check if documentation-related files were changed, and preview to generate docs from the PR's base and head, diff them, and post the result as a PR comment.
• README.md (Modified): A major update that adds comprehensive documentation for the new docs-preview workflow, as well as for previously undocumented workflows like JIRA linter and S1 CNS Scans. It also removes outdated entries.
• docs/workflows/docs-preview.md (New): A dedicated documentation file for the new workflow, which is sourced by the main README.md.
• docs/workflows/release-bot.md (New): Adds documentation for the existing release-bot workflow.
• docs/workflows/s1-cns-scan.md (New): Adds documentation for the existing s1-cns-scan workflow.

Architecture & Impact Assessment

• What this PR accomplishes: It automates the preview of documentation that is generated from source code (e.g., from Go comments or OpenAPI specs). By posting a diff in the PR, it shifts the documentation review process earlier, preventing the need for a separate, post-merge correction cycle.

• Key technical changes introduced:

  • A new reusable workflow (workflow_call) that can be adopted by other repositories.
  • The workflow uses the GitHub API to efficiently list changed files in a PR.
  • It performs a dual checkout of the PR's base and head commits to generate documentation for both states and compare them.
  • It uses a GitHub App token for elevated permissions required to access a private dependency (tyk-config-info-generator) and to request reviews from organization teams.
  • Logic for generating documentation is component-specific (e.g., for gateway, dashboard) and is explicitly mirrored from an existing process, with a plan to refactor into shared actions later.

• Affected system components: This change primarily impacts the CI/CD and PR review workflow for any repository that adopts it. It introduces a new, advisory check that enhances collaboration between developers and product managers.

Workflow Visualization

sequenceDiagram
    participant User as Developer
    participant PR as Pull Request
    participant Workflow as docs-preview.yml
    participant DetectJob as Detect Job
    participant PreviewJob as Preview Job
    participant GitHubAPI as GitHub API

    User->>PR: Pushes changes
    PR->>Workflow: Triggers on 'opened' or 'synchronize'
    Workflow->>DetectJob: Starts
    DetectJob->>GitHubAPI: Get changed files
    DetectJob->>DetectJob: Match files against 'docs_paths'
    alt Docs paths are affected
        DetectJob-->>PreviewJob: Proceeds (outputs docs_affected=true)
        PreviewJob->>PreviewJob: Checkout base and head commits
        PreviewJob->>PreviewJob: Run doc generators for both
        PreviewJob->>PreviewJob: Diff generated docs
        alt Output has changed
            PreviewJob->>GitHubAPI: Post/Update PR comment with diff
            PreviewJob->>GitHubAPI: Request team review (if configured)
        else Output is identical
            PreviewJob->>GitHubAPI: Update comment to "No impact" (if exists)
        end
    else Docs paths NOT affected
        DetectJob-->>Workflow: Skips preview (outputs docs_affected=false)
    end

Loading

Scope Discovery & Context Expansion

The changes are contained within the github-actions repository but are intended for broad, cross-repository adoption. The PR description notes that the documentation generation logic is intentionally copied from the TykTechnologies/exp repository's tyk-docs.yml workflow, indicating a wider strategic effort to standardize and improve CI/CD processes across the organization. The planned follow-up to refactor this duplicated logic into shared composite actions further supports this. The comprehensive updates to the README.md and other documentation files suggest a general initiative to improve the maintainability and usability of these shared GitHub Actions.

Metadata

• Review Effort: 4 / 5
• Primary Label: enhancement

---

Powered by Visor from Probelabs

Last updated: 2026-07-21T14:14:52.378Z | Triggered by: pr_updated | Commit: 5b63642

💡 TIP: You can chat with Visor using /visor ask <your question>

[probelabs]

Security Issues (2)

Severity	Location	Issue
🔴 Critical	.github/workflows/docs-preview.yml:260	The workflow executes a Node.js script using `sudo`, granting it root privileges on the runner. The script is sourced from an external repository (`TykTechnologies/tyk-config-info-generator`) which is not pinned to a specific commit. If that repository's `main` branch is compromised, an attacker could achieve remote code execution with root privileges, compromising the runner and potentially exfiltrating secrets. 💡 Suggestion Remove the `sudo` command. The Node.js script should be modified to write its output to a directory within the standard `${{ github.workspace }}` path, which is writable by the default runner user. Avoid writing to system-level or home directories that require elevated permissions.
🟡 Warning	.github/workflows/docs-preview.yml:131-136	The workflow checks out code from an external repository (`TykTechnologies/exp`) using a floating reference (the default branch). This creates a supply chain risk, as any new commit to this branch—including a malicious one—will be automatically executed. This issue also exists for the checkout of `TykTechnologies/tyk-config-info-generator` on line 255, which uses `ref: main`. All external actions and repository checkouts should be pinned to a specific, audited commit SHA. 💡 Suggestion Pin the repository checkouts to a specific commit SHA. For the `TykTechnologies/exp` checkout, add a `ref` property with a full commit SHA. For the `TykTechnologies/tyk-config-info-generator` checkout, replace `ref: main` with a full commit SHA.

Security Issues (2)

Severity	Location	Issue
🔴 Critical	.github/workflows/docs-preview.yml:260	The workflow executes a Node.js script using `sudo`, granting it root privileges on the runner. The script is sourced from an external repository (`TykTechnologies/tyk-config-info-generator`) which is not pinned to a specific commit. If that repository's `main` branch is compromised, an attacker could achieve remote code execution with root privileges, compromising the runner and potentially exfiltrating secrets. 💡 Suggestion Remove the `sudo` command. The Node.js script should be modified to write its output to a directory within the standard `${{ github.workspace }}` path, which is writable by the default runner user. Avoid writing to system-level or home directories that require elevated permissions.
🟡 Warning	.github/workflows/docs-preview.yml:131-136	The workflow checks out code from an external repository (`TykTechnologies/exp`) using a floating reference (the default branch). This creates a supply chain risk, as any new commit to this branch—including a malicious one—will be automatically executed. This issue also exists for the checkout of `TykTechnologies/tyk-config-info-generator` on line 255, which uses `ref: main`. All external actions and repository checkouts should be pinned to a specific, audited commit SHA. 💡 Suggestion Pin the repository checkouts to a specific commit SHA. For the `TykTechnologies/exp` checkout, add a `ref` property with a full commit SHA. For the `TykTechnologies/tyk-config-info-generator` checkout, replace `ref: main` with a full commit SHA.

\n\n ### Architecture Issues (2)

Severity	Location	Issue
🟠 Error	.github/workflows/docs-preview.yml:88-325	The `preview` job implements a monolithic design, embedding component-specific logic for five different products (`gateway`, `dashboard`, etc.) directly within the workflow, controlled by numerous `if` conditions. Furthermore, the PR description confirms this complex logic is a verbatim copy from another repository's workflow (`exp/tyk-docs.yml`). This approach introduces significant architectural issues: it violates the Single Responsibility Principle, making the workflow difficult to maintain and extend, and the cross-repository duplication creates major technical debt, requiring manual synchronization of any future changes. 💡 Suggestion To mitigate the technical debt and create a more scalable design, the component-specific generation logic should be extracted into shared, reusable composite actions, as mentioned in the PR description. This workflow should be refactored to be a pure orchestrator that calls these actions. This architectural refactoring should be prioritized to avoid solidifying a fragile, duplicated implementation.
🟡 Warning	.github/workflows/docs-preview.yml:173-208	The shell function `massage()` is defined identically in two separate `run` steps: "Generate gateway swagger" (lines 173-188) and "Generate dashboard docs" (lines 193-208). This duplication within the same file violates the DRY (Don't Repeat Yourself) principle and makes the script harder to maintain, as any changes must be applied in both places. 💡 Suggestion Refactor the script to define the `massage()` function only once. You could combine the two swagger generation steps into one, or define the function in a way that it's available to both steps (e.g., by exporting it in a previous step).

Performance Issues (2)

Severity	Location	Issue
🟡 Warning	.github/workflows/docs-preview.yml:153-247	The documentation generation for the `base` and `head` commits is performed sequentially in a series of `for side in base head; do ... done` loops. This makes the total generation time approximately the sum of the times for both commits, which can be slow and delay feedback on the pull request. 💡 Suggestion To significantly reduce the wall-clock time of this workflow, the documentation generation for the `base` and `head` commits should be parallelized. This can be achieved by refactoring the `preview` job into three separate jobs: 1. A `generate-base` job that checks out the base ref, generates its docs, and uploads the result as an artifact. 2. A `generate-head` job that runs in parallel with `generate-base`, checking out the head ref, generating its docs, and uploading its result as an artifact. 3. A final `diff-and-comment` job that depends on the completion of both generation jobs, downloads their artifacts, computes the diff, and posts the comment. This change would reduce the generation time from `T(base) + T(head)` to `max(T(base), T(head))`.
🟡 Warning	.github/workflows/docs-preview.yml:233-238	The checkout of the `TykTechnologies/tyk-config-info-generator` repository does not use `fetch-depth: 1`. This causes the runner to download the full git history for the `main` branch, which is unnecessary for this workflow and increases execution time and network usage. 💡 Suggestion Add `fetch-depth: 1` to the `with` block to perform a shallow clone, which only downloads the latest commit.

---

Powered by Visor from Probelabs

Last updated: 2026-07-21T14:14:30.143Z | Triggered by: pr_updated | Commit: 5b63642

💡 TIP: You can chat with Visor using /visor ask <your question>