CNTRLPLANE-3674: Add Jira Agent onboarding guide

[bryan-cox]

Summary

• Adds a comprehensive onboarding guide for the generic Jira Agent step registry
• Adds nav entry under CI section in mkdocs.yml

The guide covers:

• Prerequisites (GitHub App, fork repository, Vault secret, Jira configuration, plugins)
• Step-by-step setup (wrapper workflow, periodic job, generate/validate, submit PR)
• Full configuration reference (required and optional env vars)
• Credential override pattern for teams using different secrets
• JQL examples, Jira issue format, and troubleshooting

Part of the modularization effort to make the Jira Agent reusable across OpenShift teams. Companion PRs:

• CNTRLPLANE-3674: Add generic jira-agent step registry for cross-team reuse release#80927 (generic step registry + HyperShift wrapper)

Test plan

• Verify docs build with mkdocs serve
• Verify nav entry appears under CI section
• Cross-check env var table against generic step registry ref YAML

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a comprehensive Jira Agent Onboarding Guide with detailed setup prerequisites, GitHub App and Vault credential configuration steps, environment variables reference, JQL filtering query examples, team wrapper workflow creation instructions, local validation commands, and extensive troubleshooting checklists for resolving common issues when integrating projects with the OpenShift jira-agent step-registry workflow.

[openshift-merge-bot]

Pipeline controller notification
This repo is configured to use the pipeline controller. Second-stage tests will be triggered either automatically or after lgtm label is added, depending on the repository configuration. The pipeline controller will automatically detect which contexts are required and will utilize /test Prow commands to trigger the second stage.

For optional jobs, comment /test ? to see a list of all defined jobs. To trigger manually all jobs from second stage use /pipeline required command.

This repository is configured in: LGTM mode

[openshift-ci-robot]

@bryan-cox: This pull request references CNTRLPLANE-3674 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the epic to target the "5.0.0" version, but no target version was set.

Details

In response to this:

Summary

• Adds a comprehensive onboarding guide for the generic Jira Agent step registry
• Adds nav entry under CI section in mkdocs.yml

The guide covers:

• Prerequisites (GitHub App, fork repository, Vault secret, Jira configuration, plugins)
• Step-by-step setup (wrapper workflow, periodic job, generate/validate, submit PR)
• Full configuration reference (required and optional env vars)
• Credential override pattern for teams using different secrets
• JQL examples, Jira issue format, and troubleshooting

Part of the modularization effort to make the Jira Agent reusable across OpenShift teams. Companion PRs:

• CNTRLPLANE-3674: Add generic jira-agent step registry for cross-team reuse release#80927 (generic step registry + HyperShift wrapper)

Test plan

• Verify docs build with mkdocs serve
• Verify nav entry appears under CI section
• Cross-check env var table against generic step registry ref YAML

🤖 Generated with Claude Code

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited)

Review profile: CHILL

Plan: Enterprise

Run ID: c67f2813-3968-4323-b271-282881eea086

📥 Commits

Reviewing files that changed from the base of the PR and between a158b42 and d94e5f9.

📒 Files selected for processing (2)

• docs/content/how-to/ci/jira-agent-onboarding.md
• docs/mkdocs.yml

---

📝 Walkthrough

Walkthrough

This change adds a new “Jira Agent Onboarding” how-to page under the CI docs and links it from the MkDocs navigation. The guide documents the Jira Agent workflow, onboarding prerequisites, wrapper workflow and periodic job setup, required and optional environment variables, Gangway-based single-issue triggering, secret-name override refs, Jira issue description expectations, JQL examples, troubleshooting steps, and reference links to existing implementations and related documentation.

🚥 Pre-merge checks | ✅ 11

✅ Passed checks (11 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding a comprehensive Jira Agent onboarding guide documentation page.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Stable And Deterministic Test Names	✅ Passed	This PR contains only documentation changes (markdown and YAML config), with no test files or Ginkgo tests; the check does not apply to documentation-only PRs.
Test Structure And Quality	✅ Passed	This PR contains only documentation (Markdown) and configuration (YAML) files. No Ginkgo test code is present, so the test quality check is not applicable.
Topology-Aware Scheduling Compatibility	✅ Passed	PR contains only documentation (Markdown guide + MkDocs nav entry); no deployment manifests, operator code, controllers, or scheduling constraints introduced.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	This PR adds only documentation (markdown) and configuration (YAML), not Ginkgo e2e tests. The custom check applies only to new Go test files with Ginkgo patterns, so it is not applicable here.
No-Weak-Crypto	✅ Passed	PR adds documentation only (markdown files and nav entry). No code implementing cryptography is present, and no weak crypto algorithms or implementations are mentioned.
Container-Privileges	✅ Passed	This PR contains only documentation changes (markdown guide and mkdocs config); no container manifests or K8s definitions were modified, making the container-privileges check inapplicable.
No-Sensitive-Data-In-Logs	✅ Passed	Documentation discusses credentials and secrets appropriately but contains no actual credential values, logging code, or examples that expose passwords, tokens, API keys, or other sensitive data.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[openshift-ci]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: bryan-cox

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [bryan-cox]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[hypershift-jira-solve-ci]

Test Failure Analysis Complete

Job Information

• Prow Job: verify / Verify (GitHub Actions reusable workflow verify-reusable.yaml)
• Build ID: 28033109487 / Job 82978965626
• PR: CNTRLPLANE-3674: Add Jira Agent onboarding guide #8814 — CNTRLPLANE-3674: Add Jira Agent onboarding guide
• Author: bryan-cox
• Duration: ~11 minutes (14:24:55 → 14:36:01 UTC)

Test Failure Analysis

Error

docs/content/reference/aggregated-docs.md: needs update
Process completed with exit code 1.

Summary

The PR adds a new documentation file (docs/content/how-to/ci/jira-agent-onboarding.md) and updates docs/mkdocs.yml, but does not include the regenerated docs/content/reference/aggregated-docs.md. The CI verify job runs make generate update which invokes the docs-aggregate Makefile target, executing hack/tools/docs-aggregator/main.go. This tool walks all .md files under docs/content/, aggregates them into aggregated-docs.md, and the subsequent git update-index --refresh / git diff check detects the file changed, failing the build.

Root Cause

The aggregated-docs.md file is an auto-generated artifact that concatenates all markdown files found under docs/content/. The generation pipeline is:

1. make update → depends on docs-aggregate target
2. docs-aggregate → runs go run ./hack/tools/docs-aggregator/main.go
3. The aggregator walks docs/content/ recursively, finds all .md files (sorted alphabetically), strips links/images, and writes the combined output to docs/content/reference/aggregated-docs.md

PR #8814 added a new file docs/content/how-to/ci/jira-agent-onboarding.md (296 additions), which the aggregator now picks up during the CI make generate update step. Since the PR did not include the updated aggregated-docs.md, the post-generation git diff check at line 1037 of the CI log detects the drift and exits with code 1.

This is not a product bug or infrastructure issue — the PR author simply needs to run make generate update (or specifically make docs-aggregate) locally and commit the regenerated aggregated-docs.md.

Recommendations

1. Immediate fix: The PR author should run make generate update locally from the repository root and commit the updated docs/content/reference/aggregated-docs.md file to the PR branch.

2. Minimal alternative: Running just make docs-aggregate will regenerate only the aggregated docs file if the author wants a faster targeted rebuild.

3. Prevention: When adding or modifying any .md file under docs/content/, always run make update before pushing to ensure all generated artifacts are in sync.

Evidence

Evidence	Detail
Failed step	Run git update-index --refresh (step 7 of 9)
Error output	docs/content/reference/aggregated-docs.md: needs update
Exit code	1
Files in PR	docs/content/how-to/ci/jira-agent-onboarding.md (new, +296 lines), docs/mkdocs.yml (modified)
Missing file	docs/content/reference/aggregated-docs.md (not included in PR)
Generation tool	hack/tools/docs-aggregator/main.go
Makefile target	docs-aggregate (dependency of update)
Preceding steps passed	make generate update ✅, make staticcheck ✅, make fmt ✅, make vet ✅
CI workflow	openshift/hypershift/.github/workflows/verify-reusable.yaml@main

---