diff --git a/.github/workflows/zizmor.yaml b/.github/workflows/zizmor.yaml index f41825cb00..1f4478df36 100644 --- a/.github/workflows/zizmor.yaml +++ b/.github/workflows/zizmor.yaml @@ -1,5 +1,5 @@ # Workflow security analysis with zizmor. Maintainer notes: -# CONTRIBUTING.md#workflow-security-analysis +# https://main--docsydocs.netlify.app/project/about/maintainer-notes/#workflow-security-analysis name: zizmor diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 73ba1879f9..262bb39816 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,34 +1,12 @@ # How to Contribute -We'd love to accept your patches and contributions to this project. There are -just a few small guidelines you need to follow. - -## Contributor License Agreement - -Contributions to this project must be accompanied by a Contributor License -Agreement. You (or your employer) retain the copyright to your contribution; -this simply gives us permission to use and redistribute your contributions as -part of the project. Head over to to see -your current agreements on file or to sign a new one. - -You generally only need to submit a CLA once, so if you've already submitted one -(even if it was for a different project), you probably don't need to do it -again. - -## Code reviews - -All submissions, including submissions by project members, require review. We -use GitHub pull requests for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. - -## Community Guidelines - -This project follows -[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/). +See the [contribution guidelines][]. ## Maintainer notes +[Merge requirements][] and [workflow security analysis][] are project-wide (this +repo's [main ruleset][] mirrors Docsy's). + ### Dependency updates Renovate opens version-update PRs, created on Sundays, configured in @@ -113,50 +91,16 @@ npm run local -- serve The `local` prefix runs the script against the sibling Docsy, and the server watches it, so theme edits hot-reload. -### Merge requirements - -`main` is protected by a repository ruleset: changes land only through pull -requests, with linear history, no force pushes or deletions. A PR needs one -approving review from a member of the `docsy/maintainers` team, and its zizmor -analysis must be clean at the ruleset's thresholds (see -[Workflow security analysis](#workflow-security-analysis)). Maintainers (the -Maintain role or higher) can bypass the review requirement for a PR through -**Bypass rules and merge** (`gh pr merge --admin`); the bypass is logged in the -ruleset's insights. - -### Workflow security analysis - -`.github/workflows/zizmor.yaml` runs [zizmor][] over this repo's workflows in -its pedantic persona (security audits plus workflow hygiene) on every PR, on -pushes to `main`, and weekly, so the online audits catch advisories published -against already-pinned actions. Results upload to the repository's Security tab -as code-scanning alerts. - -- The job passes whatever it finds; findings are alerts to triage. Blocking - comes from the `main` ruleset's code-scanning rule: a security alert of high - or higher severity, or an error-level alert, on the PR's changed lines. -- The workflow calls the [OpenTelemetry shared workflow][otel-zizmor] at a - pinned commit; that workflow pins the zizmor action, which pins the zizmor - image by digest, so the scanner moves only when the pin here does. Review the - chain at each bump. -- CI-only by design: the repo carries no tooling dependency for it. For a local - run, with `GH_TOKEN` set for the online audits, where _`VERSION`_ is the - zizmor version the workflow's latest run logs (its `zizmor vX.Y.Z` banner): - - ```bash - uvx zizmor@VERSION --persona=pedantic . - ``` - -- `security-events: write` sits alone in this workflow, away from the job that - installs and builds. - + [alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys +[contribution guidelines]: https://main--docsydocs.netlify.app/docs/contributing/ [deploys]: https://app.netlify.com/sites/docsy-example/deploys -[Docsy]: https://github.com/google/docsy +[Docsy]: https://github.com/docsy/docsy [hugo-extended]: https://www.npmjs.com/package/hugo-extended [Hugo workspace]: https://gohugo.io/configuration/module/#top-level-settings -[otel-zizmor]: - https://github.com/open-telemetry/shared-workflows/blob/main/zizmor/README.md -[zizmor]: https://docs.zizmor.sh/ +[main ruleset]: https://github.com/docsy/docsy-example/rules/23697395 +[Merge requirements]: https://main--docsydocs.netlify.app/project/about/maintainer-notes/#merge-requirements +[workflow security analysis]: https://main--docsydocs.netlify.app/project/about/maintainer-notes/#workflow-security-analysis + diff --git a/README.md b/README.md index 39aed123b6..0995295b54 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ For build and preview problems, see the user guide's [prerequisites][] and https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-dart-sass [Docsy user guide]: https://docsy.dev/docs [hugo-extended]: https://www.npmjs.com/package/hugo-extended -[Docsy]: https://github.com/google/docsy +[Docsy]: https://github.com/docsy/docsy [maintainer notes]: CONTRIBUTING.md#maintainer-notes [example.docsy.dev]: https://example.docsy.dev [Hugo theme module]: https://gohugo.io/hugo-modules/