STONEBLD-4926 docs: add task documentation page generated from build-pipeline-tasks

[yash2189]

Summary

• Add a Task documentation page under Building → Build configuration that lists the latest version of each task from build-pipeline-tasks/task, with links to their READMEs
• Add hack/gen-task-docs.sh and npm run task-gen to regenerate the page
• Add a GitHub Actions workflow that refreshes the page weekly (Friday) or on manual run and opens a PR when it changes

Closes STONEBLD-4926

[qodo-app-for-konflux-ci]

PR Summary by Qodo

Add generated Tekton task documentation page with weekly auto-refresh

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Add an Antora page listing latest build-definitions Tekton tasks and README links.
• Add a generator script and npm target to (re)build the page locally.
• Add a scheduled GitHub Action to refresh the page weekly and open an update PR.

Diagram

graph TD
  GH["GitHub Actions workflow"] --> GEN["gen-task-docs.sh"] --> REPO[("build-definitions repo")] --> PAGE["task-documentation.adoc"] --> CPR["create-pull-request"]
  DEV["Developer"] --> NPM["npm run task-gen"] --> GEN

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Use GitHub API instead of git clone

• ➕ Less bandwidth/time than cloning a repo (even with --depth 1)
• ➕ Avoids git dependency nuances in CI runners
• ➕ Can fetch only needed metadata (task names/versions/README existence)
• ➖ More implementation complexity (pagination, rate limits, auth tokens)
• ➖ Still need semver-like sorting logic client-side

2. Pin build-definitions revision (commit/tag) for reproducible docs

• ➕ Deterministic generated output; easier to trace changes to a known upstream revision
• ➕ Reduces chance of unexpected churn from upstream default-branch changes
• ➖ Conflicts with goal of always showing the latest upstream tasks
• ➖ Requires an additional mechanism to bump the pinned revision

Recommendation: Keep the current approach (depth-1 clone + scheduled regeneration) because it is simple, transparent, and aligns with the requirement to reflect the latest upstream tasks. The GitHub API approach is a reasonable future optimization if runtime, rate limits, or cloning stability become issues.

Files changed (6) +163 / -0

Enhancement (1) +51 / -0

gen-task-docs.shAdd script to generate task-documentation.adoc from build-definitions +51/-0

Add script to generate task-documentation.adoc from build-definitions

• Adds a bash generator that clones konflux-ci/build-definitions, finds the highest semver-like version per task that contains a README.md, and writes an AsciiDoc table with links to each task's documentation.

hack/gen-task-docs.sh

Documentation (2) +41 / -0

nav.adocExpose Task documentation page in Building navigation +1/-0

Expose Task documentation page in Building navigation

• Adds a navigation entry under Building → Build configuration for the new task documentation page.

modules/building/nav.adoc

task-documentation.adocAdd generated Task documentation page with task/version table +40/-0

Add generated Task documentation page with task/version table

• Adds a generated Antora page containing a table of Tekton tasks, the latest version with a README, and a link to the upstream README in build-definitions.

modules/building/pages/task-documentation.adoc

Other (3) +71 / -0

task-documentation.yamlAdd scheduled workflow to regenerate task docs and open update PRs +66/-0

Add scheduled workflow to regenerate task docs and open update PRs

• Introduces a GitHub Actions workflow that (a) verifies on PRs that the generated page is up to date and (b) on a weekly schedule or manual dispatch regenerates the page and opens a PR via create-pull-request when changes are detected.

.github/workflows/task-documentation.yaml

.gitignoreIgnore generator working directory for task docs +4/-0

Ignore generator working directory for task docs

• Adds task-docs-gen/src to .gitignore to prevent the cloned build-definitions repository from being committed.

.gitignore

package.jsonAdd npm script to run task docs generator +1/-0

Add npm script to run task docs generator

• Adds npm run task-gen to execute hack/gen-task-docs.sh for local regeneration and consistency with CI.

package.json

[github-actions]

🚀 Preview is available at: https://pr-641--konflux-docs.netlify.app

[qodo-app-for-konflux-ci]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Pipeline errors ignored ⊘ Outdated 🐞 Bug ☼ Reliability

Description

In hack/gen-task-docs.sh, the version selection uses a pipeline in command substitution but the
script only sets set -e, so failures in earlier pipeline stages can be masked and produce an
incomplete/empty task list while the script still exits successfully.

Code

hack/gen-task-docs.sh[40]

+        done | sort -V | tail -n 1

Relevance

●●● Strong

Enabling pipefail/avoiding masked pipeline failures is a small, deterministic bash reliability fix;
likely welcomed.

PR-#460
PR-#426

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The script enables set -e but does not enable pipefail, and it relies on a pipeline to compute
version; without pipefail, upstream pipeline failures can be masked and the script can continue
with an empty/incorrect version output.

hack/gen-task-docs.sh[3-3]
hack/gen-task-docs.sh[36-41]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`hack/gen-task-docs.sh` uses a pipeline (`... | sort -V | tail -n 1`) inside a command substitution while only enabling `set -e`. In bash, without `set -o pipefail`, a failure in `sort` (or any non-last pipeline command) can be ignored because the pipeline exit status becomes the exit status of the last command (`tail`). This can silently skip tasks/versions and still produce a “successful” run.

### Issue Context
This script is invoked both by CI (GitHub Actions) and locally via `npm run task-gen`, so robust failure detection matters.

### Fix Focus Areas
- hack/gen-task-docs.sh[3-41]

### Suggested fix
- Change the script prologue to a stricter mode, e.g. `set -euo pipefail`.
- (Optional hardening) Add a clear error if required tools/flags are unavailable (e.g., validate `sort -V` capability or replace version picking with a small `python3` sorter).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Non-atomic doc generation 🐞 Bug ☼ Reliability

Description

hack/gen-task-docs.sh truncates the tracked documentation file up-front and then appends rows; if
any error occurs after truncation, the repo can be left with a partially written
task-documentation.adoc.

Code

hack/gen-task-docs.sh[R15-18]

+cat > "${dest}" <<'EOF'
+= Task documentation
+:description: Reference of Tekton tasks from the konflux-ci/build-definitions repository.
+

Relevance

●●● Strong

Reliability hardening for generated docs is low-risk; repo has accepted updates to similar hack
doc-gen scripts.

PR-#460
PR-#426

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The script first truncates the destination file, then later appends rows and the table terminator,
without using a temp file + atomic rename; therefore any failure after the first write can leave the
destination partially generated.

hack/gen-task-docs.sh[15-28]
hack/gen-task-docs.sh[30-48]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The generator overwrites `modules/building/pages/task-documentation.adoc` at the start (`cat > "${dest}" ...`) and then appends content over time. If the script fails after the initial overwrite (tool failure, filesystem error, unexpected content, etc.), the destination file can be left truncated/invalid.

### Issue Context
This is especially risky when the workflow opens an automated PR: a mid-run failure could still leave a modified (but broken) generated doc in the workspace.

### Fix Focus Areas
- hack/gen-task-docs.sh[15-48]

### Suggested fix
- Generate into a temporary file (e.g., `tmp=$(mktemp "${dest}.XXXXXX")`).
- Write the header/rows/footer to the temp file.
- On success, `mv "$tmp" "$dest"` (atomic on same filesystem).
- Add a `trap` to remove the temp file on error/exit.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[qodo-app-for-konflux-ci]

2. Non-atomic doc generation 🐞 Bug ☼ Reliability

hack/gen-task-docs.sh truncates the tracked documentation file up-front and then appends rows; if
any error occurs after truncation, the repo can be left with a partially written
task-documentation.adoc.

Agent Prompt

### Issue description
The generator overwrites `modules/building/pages/task-documentation.adoc` at the start (`cat > "${dest}" ...`) and then appends content over time. If the script fails after the initial overwrite (tool failure, filesystem error, unexpected content, etc.), the destination file can be left truncated/invalid.

### Issue Context
This is especially risky when the workflow opens an automated PR: a mid-run failure could still leave a modified (but broken) generated doc in the workspace.

### Fix Focus Areas
- hack/gen-task-docs.sh[15-48]

### Suggested fix
- Generate into a temporary file (e.g., `tmp=$(mktemp "${dest}.XXXXXX")`).
- Write the header/rows/footer to the temp file.
- On success, `mv "$tmp" "$dest"` (atomic on same filesystem).
- Add a `trap` to remove the temp file on error/exit.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[github-actions]

🚀 Preview is available at: https://pr-641--konflux-docs.netlify.app