feat: standardize workflow names and enhance documentation structure#5
Merged
Conversation
|
Caution Review failedPull request was closed or merged during review No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (13)
💤 Files with no reviewable changes (1)
✅ Files skipped from review due to trivial changes (9)
📝 WalkthroughWalkthroughAdds internal docs (content standards, release process, launch checklist), updates root READMEs/CLAUDE.md, adjusts sidebar and doc discovery, normalizes three workflow display names, and publishes new compute and private-cloud reference pages plus a CSS sidebar tweak. ChangesProcess Documentation and Workflow Updates
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
.github/workflows/20-deploy-stg.yml (1)
1-83:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd explicit least-privilege
permissionsforGITHUB_TOKEN.This workflow inherits default token scopes. Define minimal permissions explicitly to avoid excessive default access.
Suggested hardening
name: '20: Deploy Staging' +permissions: + contents: read # Manual deploy to staging from a release branch.🤖 Prompt for 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. In @.github/workflows/20-deploy-stg.yml around lines 1 - 83, Add an explicit top-level permissions block to the "20: Deploy Staging" workflow to scope GITHUB_TOKEN to the least-privilege permissions required (e.g., set contents: read for checkout and any other specific write/read permissions only where needed) instead of inheriting defaults; update the workflow (top-level, near the name: '20: Deploy Staging') to include a permissions map that only grants the minimal scopes used by the jobs (for example contents: read and any additional specific permissions required by the deploy job or scripts) so GITHUB_TOKEN is not given excessive default access..github/workflows/30-deploy-prd.yml (1)
1-116:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd explicit least-privilege
permissionsforGITHUB_TOKEN.This workflow uses default token permissions; define minimal scopes explicitly, especially given production deploy and secret usage.
Suggested hardening
name: '30: Deploy Production' +permissions: + contents: read # Manual deploy to production (docs.zcp.zsoftly.ca).🤖 Prompt for 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. In @.github/workflows/30-deploy-prd.yml around lines 1 - 116, Add an explicit least-privilege permissions block for GITHUB_TOKEN at the top of the workflow (not relying on defaults); e.g. set minimal scopes like contents: read (and any other needed read-only scopes) and avoid write permissions, and if a job truly needs elevated rights override only that job (reference the workflow name "30: Deploy Production", jobs validate/ci/deploy, and the sensitive step "04: Deploy to production via rsync" which uses secrets). Ensure the new permissions block is top-level so all jobs inherit least privilege and only grant broader permissions on a per-job basis when required..github/workflows/10-deploy-dev.yml (1)
1-43:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd explicit least-privilege
permissionsforGITHUB_TOKEN.This workflow currently relies on default token scopes. On self-hosted runners with secrets access, default broad permissions are a security posture gap; define the minimal permissions explicitly.
Suggested hardening
name: '10: Deploy Dev' +permissions: + contents: read # Auto-deploys to dev on every push to main after CI passes.🤖 Prompt for 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. In @.github/workflows/10-deploy-dev.yml around lines 1 - 43, Add an explicit top-level permissions block to the "10: Deploy Dev" workflow to limit GITHUB_TOKEN to least-privilege (e.g., set permissions: contents: read) instead of using default scopes; insert the permissions block near the top-level (alongside env) so jobs/ci and jobs/deploy inherit it, and expand the minimal permission set only if a specific step (like actions/checkout or any future API call) requires additional scopes.
🤖 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/20-deploy-stg.yml:
- Line 1: Change the workflow title to use the short environment name "stg"
instead of the word "Staging": update the YAML name value currently "20: Deploy
Staging" to follow the repo convention (for example "20: Deploy stg") so the
workflow uses the allowed short env name.
In @.github/workflows/30-deploy-prd.yml:
- Line 1: Update the GitHub Actions workflow name string used in the workflow
header (currently "30: Deploy Production") to use the repository short
environment naming convention by replacing "Production" with "prd" so the name
becomes "30: Deploy prd"; locate the workflow name declaration in the top-level
name field and make this single-word environment change to follow the guideline.
In `@docs/cicd.md`:
- Around line 48-53: The fenced code blocks in docs/cicd.md are missing language
identifiers (MD040); update each triple-backtick block that contains numbered
steps (the four blocks shown and the ones at lines 62-66, 73-79, 85-92) to
include a language tag such as "text" (e.g., change ``` to ```text) so the
linter recognizes them; ensure every fenced block in that file with plain
numbered lists or shell-like steps is updated consistently.
- Line 3: Replace all occurrences of the long environment names with the short
canonical terms: change "staging" -> "stg", "production" and "prod" -> "prd",
and any variants like "staging environment" or "production environment" to "stg"
and "prd" respectively throughout the document (including the instances noted
around the top and the block referenced by the reviewer); ensure headings,
inline text, and examples consistently use only dev/stg/prd.
In `@docs/content-standards.md`:
- Around line 123-127: The fenced tree snippet starting with "src/content/docs/"
is missing a language tag causing MD040; update the fenced code block around
that snippet by adding a language identifier (for example "text") after the
opening backticks so the block becomes ```text ... ```, leaving the tree content
unchanged.
In `@docs/environments.md`:
- Around line 9-13: The table currently uses forbidden full names
("Development", "Staging", "Production") in the "Full name" column; update the
table so all descriptive text uses the canonical short environment names `dev`,
`stg`, and `prd` only (replace "Development" -> "dev", "Staging" -> "stg",
"Production" -> "prd") and remove or reword any instances of the banned terms in
the "Never use" or other columns to comply with the repository rule; verify the
rows for the entries matching the table headers ("Name", "Full name", "Never
use") are updated accordingly.
In `@docs/release-process.md`:
- Around line 40-55: Update this section and any referenced lines to use the
short environment names `stg` and `prd` consistently: change the heading
"Releasing to stg and prd" if needed, replace occurrences like "Deploy Staging"
-> "Deploy Stg" and "Deploy Production" -> "Deploy Prd", replace any inline long
names (e.g., `stg-docs.apps...` is fine but ensure no occurrences of "staging",
"production", "staging", "prod" remain), and update the link/reference to
`launch-checklist.md` wording if it uses long names; modify the action workflow
labels "20: Deploy Staging" and "30: Deploy Production" text in this doc to
their short-name equivalents so the file follows the repo guideline to use only
`dev`, `stg`, `prd`.
- Around line 12-14: The unlabeled fenced code blocks (e.g., the block
containing "issue branch -> main -> dev (auto) -> release/YYYY-MM-DD-HHMM -> stg
(manual) -> prd (manual, same branch)") need language tags to satisfy MD040;
update those fences and the other occurrences (around the blocks at 110-114 and
128-132) by adding an appropriate language identifier (use bash for
shell/command-style lines or text for diagrams/templates) immediately after the
opening triple backticks so the fenced blocks read like ```bash or ```text.
---
Outside diff comments:
In @.github/workflows/10-deploy-dev.yml:
- Around line 1-43: Add an explicit top-level permissions block to the "10:
Deploy Dev" workflow to limit GITHUB_TOKEN to least-privilege (e.g., set
permissions: contents: read) instead of using default scopes; insert the
permissions block near the top-level (alongside env) so jobs/ci and jobs/deploy
inherit it, and expand the minimal permission set only if a specific step (like
actions/checkout or any future API call) requires additional scopes.
In @.github/workflows/20-deploy-stg.yml:
- Around line 1-83: Add an explicit top-level permissions block to the "20:
Deploy Staging" workflow to scope GITHUB_TOKEN to the least-privilege
permissions required (e.g., set contents: read for checkout and any other
specific write/read permissions only where needed) instead of inheriting
defaults; update the workflow (top-level, near the name: '20: Deploy Staging')
to include a permissions map that only grants the minimal scopes used by the
jobs (for example contents: read and any additional specific permissions
required by the deploy job or scripts) so GITHUB_TOKEN is not given excessive
default access.
In @.github/workflows/30-deploy-prd.yml:
- Around line 1-116: Add an explicit least-privilege permissions block for
GITHUB_TOKEN at the top of the workflow (not relying on defaults); e.g. set
minimal scopes like contents: read (and any other needed read-only scopes) and
avoid write permissions, and if a job truly needs elevated rights override only
that job (reference the workflow name "30: Deploy Production", jobs
validate/ci/deploy, and the sensitive step "04: Deploy to production via rsync"
which uses secrets). Ensure the new permissions block is top-level so all jobs
inherit least privilege and only grant broader permissions on a per-job basis
when required.
🪄 Autofix (Beta)
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: defaults
Review profile: CHILL
Plan: Pro
Run ID: 8e49e6da-bbcb-45d6-809b-018abf0bef30
📒 Files selected for processing (11)
.github/workflows/10-deploy-dev.yml.github/workflows/20-deploy-stg.yml.github/workflows/30-deploy-prd.ymlCLAUDE.mdREADME.mddocs/README.mddocs/cicd.mddocs/content-standards.mddocs/environments.mddocs/launch-checklist.mddocs/release-process.md
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (4)
docs/release-process.md (4)
51-55:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd language tag to fenced code block.
This code fence should be labeled
textto satisfy the MD040 linting rule.📝 Proposed fix
-``` +```text <type>: <short summary> [optional body]</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/release-process.mdaround lines 51 - 55, The fenced code block in
release-process.md that shows ": " must include a language
tag to satisfy MD040; update that block by adding the "text" language identifier
after the opening backticks (i.e., change the opening fence to ```text) so the
example becomes a labeled text code block and conforms to the lint rule.</details> --- `12-14`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Add language tag to fenced code block.** This code fence should be labeled `text` to satisfy the MD040 linting rule. <details> <summary>📝 Proposed fix</summary> ```diff -``` +```text branch -> open PR -> CI passes -> merge to main -> published ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/release-process.mdaround lines 12 - 14, The fenced code block
containing "branch -> open PR -> CI passes -> merge to main -> published" needs
a language tag to satisfy MD040; update the block by changing the opening
backticks to include thetexttag (i.e., replace "" with "text" for that
specific block) so the lint rule is satisfied.</details> --- `30-31`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Replace `staging` and `production` with `stg` and `prd`.** The text uses "staging and production stages" instead of the short environment names. As per coding guidelines, use `stg` and `prd` instead of `staging` and `production`. <details> <summary>📝 Proposed fix</summary> ```diff - ZSoftly's internal deployment pipeline. Maintainers handle promotion through the staging and - production stages. + ZSoftly's internal deployment pipeline. Maintainers handle promotion through the stg and + prd stages. ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/release-process.md` around lines 30 - 31, Update the sentence that currently reads "staging and production stages" to use the short environment names: replace it with "stg and prd" (preferably formatted as `stg` and `prd` to match guidelines), ensuring the surrounding sentence ("ZSoftly's internal deployment pipeline. Maintainers handle promotion through the staging and production stages.") becomes "ZSoftly's internal deployment pipeline. Maintainers handle promotion through the `stg` and `prd` stages." and keep punctuation and capitalization consistent. ``` </details> --- `69-72`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_ **Add language tag to fenced code block.** This code fence should be labeled `text` to satisfy the MD040 linting rule. <details> <summary>📝 Proposed fix</summary> ```diff -``` +```text content: rewrite DNS domains page and add registrar reference fix: correct S3 endpoint for the YOW region ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/release-process.mdaround lines 69 - 72, The fenced code block
containing the two-line commit-style snippet (the block starting withand the lines "content: rewrite DNS domains page and add registrar reference" and "fix: correct S3 endpoint for the YOW region") is missing a language tag; update that fenced block to use the text language tag (i.e., changeto ```text) so
the MD040 lint rule is satisfied.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>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@src/content/docs/public-cloud/compute/plan-names.md:
- Around line 15-21: The fenced ASCII diagram beginning with "ca2.l" is missing
a language tag which triggers MD040; update the code fence for that diagram (the
block containing "ca2.l" and the following lines with box-drawing characters) to
use the text language tag by changing the opening fence fromtotext so
the block is explicitly labeled as plain text.- Around line 26-35: Add the missing language tag to the fenced ASCII diagram
block: locate the triple-backtick fenced block that begins with the diagram line
"cam2.2xl ca2s.s" and change the opening fence fromtotext so the
block is explicitly labeled as text (satisfying MD040 linting).
Duplicate comments:
In@docs/release-process.md:
- Around line 51-55: The fenced code block in release-process.md that shows
": " must include a language tag to satisfy MD040; update
that block by adding the "text" language identifier after the opening backticks
(i.e., change the opening fence to ```text) so the example becomes a labeled
text code block and conforms to the lint rule.- Around line 12-14: The fenced code block containing "branch -> open PR -> CI
passes -> merge to main -> published" needs a language tag to satisfy MD040;
update the block by changing the opening backticks to include thetexttag
(i.e., replace "" with "text" for that specific block) so the lint rule is
satisfied.- Around line 30-31: Update the sentence that currently reads "staging and
production stages" to use the short environment names: replace it with "stg and
prd" (preferably formatted asstgandprdto match guidelines), ensuring the
surrounding sentence ("ZSoftly's internal deployment pipeline. Maintainers
handle promotion through the staging and production stages.") becomes "ZSoftly's
internal deployment pipeline. Maintainers handle promotion through thestgand
prdstages." and keep punctuation and capitalization consistent.- Around line 69-72: The fenced code block containing the two-line commit-style
snippet (the block starting withand the lines "content: rewrite DNS domains page and add registrar reference" and "fix: correct S3 endpoint for the YOW region") is missing a language tag; update that fenced block to use the text language tag (i.e., changeto ```text) so the MD040 lint rule is satisfied.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `727cf949-fc4d-4980-8889-6390eaeb41d2` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 2344ef802c8a8179c9e1d34f2e24183cf81e7a0a and 8e5ca5a05cdccab1b7154ef111395c17820c5622. </details> <details> <summary>📒 Files selected for processing (9)</summary> * `.github/ISSUE_TEMPLATE/doc-error.yml` * `.github/workflows/30-deploy-prd.yml` * `CLAUDE.md` * `README.md` * `astro.config.mjs` * `docs/README.md` * `docs/launch-checklist.md` * `docs/release-process.md` * `src/content/docs/public-cloud/compute/plan-names.md` </details> <details> <summary>💤 Files with no reviewable changes (1)</summary> * .github/workflows/30-deploy-prd.yml </details> <details> <summary>✅ Files skipped from review due to trivial changes (4)</summary> * .github/ISSUE_TEMPLATE/doc-error.yml * README.md * docs/launch-checklist.md * CLAUDE.md </details> <details> <summary>🚧 Files skipped from review as they are similar to previous changes (1)</summary> * docs/README.md </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
…& SSO, and instance types; update existing content for clarity and accuracy
ditahm6
approved these changes
Jun 1, 2026
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
2 participants
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.
What changed
Why
Checklist
pnpm fmt && pnpm lint && pnpm typecheck && pnpm buildall pass:::note Screenshot pending:::if unavailableSummary by CodeRabbit
New Features
Documentation
Chores