From e9e08fb8dca14c63d5044cc73ba30ba61e6c3c70 Mon Sep 17 00:00:00 2001 From: Oto Macenauer Date: Tue, 4 Aug 2026 13:16:07 +0200 Subject: [PATCH 1/5] feat(docs): onboard docs to the AbsaOSS knowledge base Adds the zero-config single-page onboarding: one workflow renders docs/index.md and docs/security/security.md into a headless bundle and attaches dist.tar.gz to the published release. - new .github/workflows/publish_docs.yml (release: published + workflow_dispatch with an optional release-tag input) - new docs/index.md overview page, frontmatter-free - docs/security/security.md: root-relative links replaced with absolute GitHub URLs, which resolve against the knowledge-base origin otherwise Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01GdafNH5D2xP8QNjo1yBE8Y --- .github/workflows/publish_docs.yml | 58 ++++++++++++++++++++++++++++++ docs/index.md | 31 ++++++++++++++++ docs/security/security.md | 11 +++--- 3 files changed, 95 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/publish_docs.yml create mode 100644 docs/index.md diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml new file mode 100644 index 0000000..ad66d82 --- /dev/null +++ b/.github/workflows/publish_docs.yml @@ -0,0 +1,58 @@ +# +# Copyright 2026 ABSA Group Limited +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +name: Publish Docs + +on: + release: + types: [ published ] + workflow_dispatch: + inputs: + release-tag: + description: 'Release tag to attach the docs bundle to. Default value: latest release.' + required: false + +jobs: + publish: + name: Publish Docs to the Knowledge Base + runs-on: ubuntu-latest + permissions: + contents: write # required - the action uploads a release asset + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 + with: + persist-credentials: false + + - name: Render and publish single-page docs + uses: AbsaOSS/knowledge-base/actions/publish-single-page-docs@master + with: + # Empty on the release trigger, where the event tag is used instead. + # Empty on both - the action resolves the repository's latest release. + release-tag: ${{ inputs.release-tag || github.event.release.tag_name }} + docs: | + - md: docs/index.md + title: Organizational Workflows + description: Reusable GitHub Actions workflows with Python automation backends, shared across the organization. + slug: org-workflows + icon: collection + tags: [workflows, automation] + - md: docs/security/security.md + title: Security Automation + description: Turns AquaSec scan findings into a managed GitHub Issues backlog with full lifecycle automation. + slug: org-workflows-security + icon: shield + tags: [security, automation] diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..6fafc26 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,31 @@ +# Organizational Workflows + +A collection of reusable GitHub Actions workflows with Python automation backends, designed to be +shared across an organization. Each solution is self-contained: a reusable workflow and dedicated +documentation. + +## Solutions + +| Solution | What it does | +| --- | --- | +| [Security Automation](/knowledge-base/org-workflows-security/) | Turns AquaSec scan findings into a managed GitHub Issues backlog with full lifecycle automation. | + +## Repository Layout + +```text +.github/workflows/ # reusable GitHub Actions workflows (the product) +src/ + core/ # shared utilities (GitHub API, config, helpers) + security/ # security automation scripts & modules +docs/ + security/ # business-level documentation & example workflows +tests/ # all tests (mirrors src/ structure) +``` + +## Links + +- [Repository README](https://github.com/AbsaOSS/organizational-workflows/blob/master/README.md) +- [Developer Guide](https://github.com/AbsaOSS/organizational-workflows/blob/master/DEVELOPERS.md) +- [Contributing Guide](https://github.com/AbsaOSS/organizational-workflows/blob/master/CONTRIBUTING.md) +- [Issues](https://github.com/AbsaOSS/organizational-workflows/issues) +- [Discussions](https://github.com/AbsaOSS/organizational-workflows/discussions) diff --git a/docs/security/security.md b/docs/security/security.md index b0f05db..19a4cee 100644 --- a/docs/security/security.md +++ b/docs/security/security.md @@ -4,7 +4,7 @@ Security Automation provides **continuous, automated vulnerability management** for your repositories. It authenticates directly with the AquaSec API, fetches scan findings, and automatically converts them into structured **GitHub Issues** with full lifecycle management. This gives your team a managed security posture without manual triage effort. -> For setup instructions and technical configuration, see the [Security README](/src/security/README.md). +> For setup instructions and technical configuration, see the [Security README](https://github.com/AbsaOSS/organizational-workflows/blob/master/src/security/README.md). --- @@ -179,12 +179,13 @@ Adopt the security automation by adding a short caller workflow to your reposito ### Example Caller Workflow -See the full example at [docs/security/aquasec-night-scan-example.yml](/docs/security/aquasec-night-scan-example.yml). +See the full example at [aquasec-night-scan-example.yml](https://github.com/AbsaOSS/organizational-workflows/blob/master/docs/security/aquasec-night-scan-example.yml). --- ## See Also -- [Security README](/src/security/README.md): setup instructions, shared workflow configuration, and technical details -- [Example Caller Workflow](/docs/security/aquasec-night-scan-example.yml): ready-to-copy workflow file for your repository -- [Repository README](/README.md): overview of all organizational workflows +- [Security README](https://github.com/AbsaOSS/organizational-workflows/blob/master/src/security/README.md): setup instructions, shared workflow configuration, and technical details +- [Example Caller Workflow](https://github.com/AbsaOSS/organizational-workflows/blob/master/docs/security/aquasec-night-scan-example.yml): ready-to-copy workflow file for your repository +- [Overview](/knowledge-base/org-workflows/): all organizational workflows +- [Repository README](https://github.com/AbsaOSS/organizational-workflows/blob/master/README.md): overview of all organizational workflows From d187c9f128102a26473af3d76d6a3d51ed6e84b8 Mon Sep 17 00:00:00 2001 From: Oto Macenauer Date: Tue, 4 Aug 2026 13:23:52 +0200 Subject: [PATCH 2/5] fix(docs): publish only the security page to the knowledge base Drop docs/index.md from the publish definition and from the repository. The knowledge base catalogue already lists every registered app, so a per-repo overview page duplicated that landing without adding anything. Remove the overview back-link from the security page along with it. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01GdafNH5D2xP8QNjo1yBE8Y --- .github/workflows/publish_docs.yml | 6 ------ docs/index.md | 31 ------------------------------ docs/security/security.md | 1 - 3 files changed, 38 deletions(-) delete mode 100644 docs/index.md diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml index ad66d82..9e7b32c 100644 --- a/.github/workflows/publish_docs.yml +++ b/.github/workflows/publish_docs.yml @@ -44,12 +44,6 @@ jobs: # Empty on both - the action resolves the repository's latest release. release-tag: ${{ inputs.release-tag || github.event.release.tag_name }} docs: | - - md: docs/index.md - title: Organizational Workflows - description: Reusable GitHub Actions workflows with Python automation backends, shared across the organization. - slug: org-workflows - icon: collection - tags: [workflows, automation] - md: docs/security/security.md title: Security Automation description: Turns AquaSec scan findings into a managed GitHub Issues backlog with full lifecycle automation. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 6fafc26..0000000 --- a/docs/index.md +++ /dev/null @@ -1,31 +0,0 @@ -# Organizational Workflows - -A collection of reusable GitHub Actions workflows with Python automation backends, designed to be -shared across an organization. Each solution is self-contained: a reusable workflow and dedicated -documentation. - -## Solutions - -| Solution | What it does | -| --- | --- | -| [Security Automation](/knowledge-base/org-workflows-security/) | Turns AquaSec scan findings into a managed GitHub Issues backlog with full lifecycle automation. | - -## Repository Layout - -```text -.github/workflows/ # reusable GitHub Actions workflows (the product) -src/ - core/ # shared utilities (GitHub API, config, helpers) - security/ # security automation scripts & modules -docs/ - security/ # business-level documentation & example workflows -tests/ # all tests (mirrors src/ structure) -``` - -## Links - -- [Repository README](https://github.com/AbsaOSS/organizational-workflows/blob/master/README.md) -- [Developer Guide](https://github.com/AbsaOSS/organizational-workflows/blob/master/DEVELOPERS.md) -- [Contributing Guide](https://github.com/AbsaOSS/organizational-workflows/blob/master/CONTRIBUTING.md) -- [Issues](https://github.com/AbsaOSS/organizational-workflows/issues) -- [Discussions](https://github.com/AbsaOSS/organizational-workflows/discussions) diff --git a/docs/security/security.md b/docs/security/security.md index 19a4cee..0995085 100644 --- a/docs/security/security.md +++ b/docs/security/security.md @@ -187,5 +187,4 @@ See the full example at [aquasec-night-scan-example.yml](https://github.com/Absa - [Security README](https://github.com/AbsaOSS/organizational-workflows/blob/master/src/security/README.md): setup instructions, shared workflow configuration, and technical details - [Example Caller Workflow](https://github.com/AbsaOSS/organizational-workflows/blob/master/docs/security/aquasec-night-scan-example.yml): ready-to-copy workflow file for your repository -- [Overview](/knowledge-base/org-workflows/): all organizational workflows - [Repository README](https://github.com/AbsaOSS/organizational-workflows/blob/master/README.md): overview of all organizational workflows From 7ecefad0490e10ed7384384e1f9e356466584ac0 Mon Sep 17 00:00:00 2001 From: Oto Macenauer Date: Tue, 4 Aug 2026 13:30:46 +0200 Subject: [PATCH 3/5] fix(docs): address CodeRabbit review feedback on PR #93 Pin the knowledge-base publishing action to a commit SHA. The job grants contents: write, so a mutable @master ref would let upstream changes run with a token that can write release assets. Every other action in this repository is pinned the same way, and the Dependabot github-actions group already covers the bump. Use the American spelling of "organizational" consistently. --- .github/workflows/publish_docs.yml | 2 +- docs/security/security.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml index 9e7b32c..93a6d70 100644 --- a/.github/workflows/publish_docs.yml +++ b/.github/workflows/publish_docs.yml @@ -38,7 +38,7 @@ jobs: persist-credentials: false - name: Render and publish single-page docs - uses: AbsaOSS/knowledge-base/actions/publish-single-page-docs@master + uses: AbsaOSS/knowledge-base/actions/publish-single-page-docs@679ec075cab1e1cdfb1140eedad7f2f80a5b683a with: # Empty on the release trigger, where the event tag is used instead. # Empty on both - the action resolves the repository's latest release. diff --git a/docs/security/security.md b/docs/security/security.md index 0995085..44cd914 100644 --- a/docs/security/security.md +++ b/docs/security/security.md @@ -50,7 +50,7 @@ flowchart TD - **Lifecycle automation**: Issues are reopened when findings reappear, automatically closed when resolved, and updated if needed. - **Notifications**: Option to notify the team of new or reopened security findings in real-time. - **Priority sync**: Findings are mapped to priority levels on a ProjectV2 board, keeping planning and security aligned. -- **Organisational scale**: Shared reusable workflows mean every repository gets the same security process with a single caller workflow. +- **Organizational scale**: Shared reusable workflows mean every repository gets the same security process with a single caller workflow. --- From a108bd0042f86c396c762014e3e5056d5592b467 Mon Sep 17 00:00:00 2001 From: Oto Macenauer Date: Tue, 4 Aug 2026 14:30:15 +0200 Subject: [PATCH 4/5] docs: add aquasec and workflows tags, clarify release-tag Tags render as pills on the knowledge base catalogue card, so add the two that readers are most likely to search the library for. Spell out how release-tag resolves under each trigger. The one-line comment did not make clear that the input only ever appears on a manual dispatch, which was the question raised in review. --- .github/workflows/publish_docs.yml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml index 93a6d70..8f0177f 100644 --- a/.github/workflows/publish_docs.yml +++ b/.github/workflows/publish_docs.yml @@ -22,7 +22,7 @@ on: workflow_dispatch: inputs: release-tag: - description: 'Release tag to attach the docs bundle to. Default value: latest release.' + description: 'Release tag to attach the docs bundle to. Leave empty to use the latest release.' required: false jobs: @@ -40,8 +40,12 @@ jobs: - name: Render and publish single-page docs uses: AbsaOSS/knowledge-base/actions/publish-single-page-docs@679ec075cab1e1cdfb1140eedad7f2f80a5b683a with: - # Empty on the release trigger, where the event tag is used instead. - # Empty on both - the action resolves the repository's latest release. + # Which release the docs bundle is attached to, by trigger: + # release: published - inputs.release-tag is empty, so the tag of the + # release that fired the event is used. + # workflow_dispatch - the tag typed into the Run workflow form, or, + # when left empty, both sides resolve to empty + # and the action falls back to the latest release. release-tag: ${{ inputs.release-tag || github.event.release.tag_name }} docs: | - md: docs/security/security.md @@ -49,4 +53,4 @@ jobs: description: Turns AquaSec scan findings into a managed GitHub Issues backlog with full lifecycle automation. slug: org-workflows-security icon: shield - tags: [security, automation] + tags: [security, automation, aquasec, workflows] From 93e6a745a88048bc60dfb4ed46463cad75aa15c5 Mon Sep 17 00:00:00 2001 From: Oto Macenauer Date: Tue, 4 Aug 2026 14:49:39 +0200 Subject: [PATCH 5/5] docs: trim the release-tag comment to one line The per-trigger breakdown duplicated the workflow_dispatch input description. Requested in review. --- .github/workflows/publish_docs.yml | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml index 8f0177f..034d42a 100644 --- a/.github/workflows/publish_docs.yml +++ b/.github/workflows/publish_docs.yml @@ -40,12 +40,7 @@ jobs: - name: Render and publish single-page docs uses: AbsaOSS/knowledge-base/actions/publish-single-page-docs@679ec075cab1e1cdfb1140eedad7f2f80a5b683a with: - # Which release the docs bundle is attached to, by trigger: - # release: published - inputs.release-tag is empty, so the tag of the - # release that fired the event is used. - # workflow_dispatch - the tag typed into the Run workflow form, or, - # when left empty, both sides resolve to empty - # and the action falls back to the latest release. + # Which release the docs bundle is attached to release-tag: ${{ inputs.release-tag || github.event.release.tag_name }} docs: | - md: docs/security/security.md