feat(docs): publish documentation to the AbsaOSS knowledge base

[oto-macenauer-absa]

Overview

Onboards this repository's documentation into the AbsaOSS knowledge base using its single-page mechanism — the zero-config path for repos whose docs are plain markdown rather than a docs site.

The knowledge base recently gained this capability, so no MkDocs orchestration, theme, build script, marketplace.json, or packing tooling is needed here. The entire repo-side cost is one workflow file.

What was added

• .github/workflows/publish_docs.yml — runs on release: published and on manual workflow_dispatch (with an optional release-tag input). It calls the reusable AbsaOSS/knowledge-base/actions/publish-single-page-docs action, which renders the markdown into headless HTML, packs it as dist.tar.gz with a bundle.json manifest, and attaches it to the release. The knowledge base picks it up on its next build.
• docs/security/security.md — root-relative links (/src/security/README.md, /README.md, the example workflow YAML) replaced with absolute GitHub URLs, since published pages are re-hosted under the knowledge base origin where those paths would 404.

One doc is published, the Security Automation page, getting its own catalogue card and URL:

Slug	Title	URL
org-workflows-security	Security Automation	/knowledge-base/org-workflows-security/

No repository overview page is published — the knowledge base catalogue already lists every registered app, so a per-repo landing would only duplicate it.

Notes

• release-tag is wired as ${{ inputs.release-tag || github.event.release.tag_name }}. Passing the dispatch input bare would supply an empty string on the release trigger and suppress the action's own default, causing it to fall back to "latest release" — wrong for a pre-release or a non-newest release. This form is exact on release: published and falls back correctly on a bare dispatch.
• The published markdown intentionally carries no YAML frontmatter and no repo-relative image or .md links: the action does not strip frontmatter, and each doc becomes an independently hosted app, so those references would render as literal text or 404.
• Verified by running the action's renderer locally against this branch: exit 0, count=1, valid bundle.json, data-mp-headless="true", mermaid vendored into the artifact, and every rendered link either an in-page anchor or an absolute URL.

Follow-up (separate repo)

Publishing is only half the loop — the knowledge base also needs a registry entry. That is a one-line PR against AbsaOSS/knowledge-base adding to apps.json:

{ "repo": "AbsaOSS/organizational-workflows", "type": "single-page", "version": "latest" }

No slug, name, or description there — all of it is discovered from the bundle, so adding or renaming a doc later never touches the knowledge base repo again.

This also supersedes #91 (the MkDocs showcase-site approach), which can be closed.

Release Notes

• Added a Publish Docs workflow that publishes the Security Automation documentation to the AbsaOSS knowledge base on every published release, and on manual dispatch.
• Fixed links in the Security Automation documentation that broke when the page is served outside the repository.

Related

Closes #92

Summary by CodeRabbit

• New Features

  • Documentation can now be published to the Knowledge Base automatically when a release is published or manually on demand.
  • Security automation documentation is published as single-page entries for easier access.

• Documentation

  • Updated security documentation links to point directly to GitHub pages.
  • Improved wording for organizational scale references.

[coderabbitai]

Warning

Review limit reached

@oto-macenauer-absa, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 40 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f19515f6-8ef3-4241-a87d-82da38e18059

📥 Commits

Reviewing files that changed from the base of the PR and between a108bd0 and 93e6a74.

📒 Files selected for processing (1)

• .github/workflows/publish_docs.yml

Walkthrough

This change adds a GitHub Actions workflow, "Publish Docs," that runs on release publication or manual dispatch to publish security automation documentation to the Knowledge Base. It also updates security documentation links from relative paths to absolute GitHub URLs and corrects a label typo.

Changes

Documentation publication

Layer / File(s)	Summary
Security documentation links and terminology docs/security/security.md	Links to the Security README, example workflow, and See Also section change from relative paths to absolute GitHub URLs. The label "Organisational scale" is corrected to "Organizational scale."
Knowledge Base publication workflow .github/workflows/publish_docs.yml	A new workflow, "Publish Docs," triggers on release publication or manual dispatch, checks out the repository with disabled credential persistence, resolves an optional release-tag input, and invokes the Knowledge Base action to publish the security automation documentation page with title, description, slug, icon, and tags metadata.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Release as Release publication or manual dispatch
  participant Actions as GitHub Actions
  participant Repository as Repository checkout
  participant KnowledgeBase as Knowledge Base
  Release->>Actions: Start Publish Docs workflow
  Actions->>Repository: Checkout repository and resolve release tag
  Actions->>KnowledgeBase: Publish security automation documentation

Loading

Possibly related PRs

• AbsaOSS/organizational-workflows#54: Both PRs modify docs/security/security.md; this PR updates links and terminology after the earlier rewrite.

Suggested reviewers: miroslavpojer

Poem

A hop, a skip, a workflow born,
Docs now travel, links reform.
"Organizational" stands correct and true,
Knowledge Base awaits its cue.
🐇 Publish, checkout, tag resolved —
This rabbit's docs are now evolved!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The workflow creates and publishes the documentation bundle, but knowledge-base registry configuration remains a separate follow-up, so issue #92 is not fully addressed.	Include the knowledge-base registry entry or split and track the remaining ingestion work so issue #92 has complete implementation coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states that the pull request adds documentation publishing to the AbsaOSS knowledge base.
Description check	✅ Passed	The description includes the required Overview, Release Notes, and Related sections with relevant implementation details.
Out of Scope Changes check	✅ Passed	The workflow and link updates support documentation publishing and hosted-page correctness, with no unrelated code changes identified.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/kb-single-page-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/publish_docs.yml:
- Line 41: Update the publish-single-page-docs action reference in the workflow
to use a full immutable commit SHA instead of the mutable master tag, while
preserving the existing action and permissions configuration.

In `@docs/security/security.md`:
- Line 190: Standardize the spelling in docs/security/security.md by changing
“Organisational scale” to “Organizational scale” and retaining “organizational
workflows” in the link description, matching the document title and
docs/index.md.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1df34e84-a807-403b-a47d-09d03f07e574

📥 Commits

Reviewing files that changed from the base of the PR and between abae613 and e9e08fb.

📒 Files selected for processing (3)

• .github/workflows/publish_docs.yml
• docs/index.md
• docs/security/security.md

[tmikula-dev]

I really like this new way of generating the workflow. Please only see one config comment below.

[tmikula-dev]

one nitpick please

[tmikula-dev]

GJ