Docs: restructure architecture and guides around CSSC stages#132
Merged
Conversation
Reorganize docs/architecture/ and docs/guides/ around the five CSSC framework
stages (Acquire, Catalog, Build, Deploy, Run). Within each stage, documents are
grouped under two cross-cutting themes where they apply — Authenticity and
Integrity, and Supply Chain Observability — as index subsections (stages stay
the primary structure). docs/reference/ and docs/contributing/ remain
cross-cutting top-level areas.
Moves:
- architecture/workflows/image-mirror-workflows.md -> architecture/acquire/
- architecture/workflows/promote-from-quarantine{,-override-approval}.md -> catalog/
- architecture/workflows/build-workflows.md -> architecture/build/
- architecture/workflows/ci-failure-notifications.md -> architecture/cross-cutting/
- architecture/apps/cssc-dashboard.md -> architecture/run/
- guides/mirroring-base-images.md -> guides/acquire/
- guides/configuring-override-approval.md -> guides/catalog/
- guides/{image-tagging,reading-image-annotations,verifying-image-attestations}.md -> guides/build/
Add per-stage index READMEs (architecture + guides) with theme subsections;
rewrite the top docs/architecture, docs/guides, and docs README indexes around
the stages. Update every internal cross-link plus external references (workflow
comments, the build documentation annotation, and the app READMEs) to the new
paths. Verified no dead links.
Closes #127
There was a problem hiding this comment.
Pull request overview
Restructures repository documentation so architecture and guides are organized by the five CSSC stages (Acquire, Catalog, Build, Deploy, Run), with cross-cutting design docs under architecture/cross-cutting/. The PR also updates internal/external cross-links (including workflow comments and an OCI org.opencontainers.image.documentation annotation) to point at the moved docs.
Changes:
- Reorganized
docs/architecture/anddocs/guides/into per-stage subfolders with new per-stage index READMEs and updated top-level doc indexes. - Moved/renamed existing stage-relevant docs into the new structure (Acquire/Catalog/Build/Run) and introduced placeholder indexes for Deploy/Run guides and Deploy architecture.
- Updated cross-links in docs plus link-only references in workflows/actions and app READMEs to reflect the new doc locations.
Reviewed changes
Copilot reviewed 39 out of 42 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/reference/workflow-actions.md | Updates cross-link to moved promote-from-quarantine architecture doc. |
| docs/reference/image-annotations.md | Updates cross-link to the moved image tagging guide. |
| docs/README.md | Rewrites top-level docs entrypoint around stage-based structure. |
| docs/guides/run/README.md | Adds Run-stage guides index placeholder. |
| docs/guides/README.md | Replaces topic list with per-stage guide navigation. |
| docs/guides/deploy/README.md | Adds Deploy-stage guides index placeholder. |
| docs/guides/catalog/README.md | Adds Catalog-stage guides index and theme grouping. |
| docs/guides/catalog/configuring-override-approval.md | Fixes relative links after moving guide under guides/catalog/. |
| docs/guides/build/verifying-image-attestations.md | Fixes relative links after moving guide under guides/build/. |
| docs/guides/build/README.md | Adds Build-stage guides index with theme grouping. |
| docs/guides/build/reading-image-annotations.md | Fixes relative links after moving guide under guides/build/. |
| docs/guides/build/image-tagging.md | Fixes relative links and architecture cross-link after moving guide under guides/build/. |
| docs/guides/acquire/README.md | Adds Acquire-stage guides index and theme grouping. |
| docs/guides/acquire/mirroring-base-images.md | Fixes relative links after moving guide under guides/acquire/. |
| docs/contributing/workflow-naming.md | Updates architecture doc references to new paths. |
| docs/architecture/workflows/README.md | Removes obsolete workflows-topic index under the old structure. |
| docs/architecture/run/README.md | Adds Run-stage architecture index. |
| docs/architecture/run/cssc-dashboard.md | Adds Run-stage CSSC Dashboard architecture doc under new structure. |
| docs/architecture/README.md | Rewrites architecture entrypoint to stage-based navigation + cross-cutting section. |
| docs/architecture/deploy/README.md | Adds Deploy-stage architecture index placeholder. |
| docs/architecture/cross-cutting/README.md | Adds cross-cutting architecture index. |
| docs/architecture/cross-cutting/ci-failure-notifications.md | Moves CI failure notifications doc under cross-cutting and updates internal links. |
| docs/architecture/catalog/README.md | Adds Catalog-stage architecture index and theme grouping. |
| docs/architecture/catalog/promote-from-quarantine-workflows.md | Moves promote-from-quarantine workflows architecture doc under Catalog and updates links. |
| docs/architecture/catalog/promote-from-quarantine-override-approval.md | Moves override-approval design doc under Catalog. |
| docs/architecture/build/README.md | Adds Build-stage architecture index and reference cross-links. |
| docs/architecture/build/build-workflows.md | Moves build workflows architecture doc under Build and updates links. |
| docs/architecture/apps/README.md | Removes obsolete apps-topic index under the old structure. |
| docs/architecture/acquire/README.md | Adds Acquire-stage architecture index. |
| docs/architecture/acquire/image-mirror-workflows.md | Moves image mirror workflows doc under Acquire and updates links. |
| apps/python-app/services/packages-service/README.md | Updates CSSC Dashboard design link to new docs location. |
| apps/python-app/services/issues-service/README.md | Updates CSSC Dashboard design link to new docs location. |
| apps/python-app/services/dashboard-web/README.md | Updates CSSC Dashboard design link to new docs location. |
| apps/python-app/README.md | Updates CSSC Dashboard design link to new docs location. |
| apps/python-app/libs/cssc_common/README.md | Updates CSSC Dashboard design link to new docs location. |
| .github/workflows/report-ci-failure.yml | Updates comment link to moved CI failure notifications doc. |
| .github/workflows/promote-override.yml | Updates comment link to moved override-approval design doc. |
| .github/workflows/build-cssc-dashboard.yml | Updates org.opencontainers.image.documentation annotation URL to new doc path. |
| .github/workflows/_promote-override.yml | Updates comment link to moved override-approval design doc. |
| .github/workflows/_promote-from-quarantine.yml | Updates comment link to moved promote-from-quarantine architecture doc. |
| .github/workflows/_promote-from-quarantine-sbom.yml | Updates comment link to moved promote-from-quarantine architecture doc. |
| .github/actions/manage-failure-issue/action.yml | Updates comment link to moved CI failure notifications doc. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #127.
Reorganizes
docs/architecture/anddocs/guides/around the five CSSC framework stages — Acquire, Catalog, Build, Deploy, Run.Decisions (agreed up front)
docs/architecture/<stage>/anddocs/guides/<stage>/.docs/reference/anddocs/contributing/stay as cross-cutting top-level areas.docs/architecture/cross-cutting/.Moves
architecture/workflows/image-mirror-workflows.mdarchitecture/acquire/architecture/workflows/promote-from-quarantine-workflows.mdarchitecture/catalog/architecture/workflows/promote-from-quarantine-override-approval.mdarchitecture/catalog/architecture/workflows/build-workflows.mdarchitecture/build/architecture/workflows/ci-failure-notifications.mdarchitecture/cross-cutting/architecture/apps/cssc-dashboard.mdarchitecture/run/guides/mirroring-base-images.mdguides/acquire/guides/configuring-override-approval.mdguides/catalog/guides/image-tagging.md,reading-image-annotations.md,verifying-image-attestations.mdguides/build/Also
docs/README.md,docs/architecture/README.md,docs/guides/README.md.org.opencontainers.image.documentationannotation inbuild-cssc-dashboard.yml(now points atarchitecture/run/cssc-dashboard.md), and the app READMEs.Validation
actionlintshellcheck info/style notes in the promote workflows are unchanged by this PR.