Repository navigation
Document the cloud policy - #118
Conversation
Rewrite concepts/policy to explain the two kinds of policy: the cloud policy of a tenant and policy as code in a repository. Add four concept pages for the cloud policy: policy resolution, labels, package rules, and policy revisions and changes. Put them and concepts/cel in a nested "Policy" group under Core Concepts. No URL changes. concepts/policy no longer says that vet-action has a "paranoid" input or a conventional policy path, because the products map lists neither. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
Add a "Cloud Policy" group after "SafeDep Cloud", with a landing page, a quickstart and how-to guides: block a package, trust a package, set a cooldown, target a group, fail pull request checks, roll back a change, explain a decision and audit policy changes. Move governance/cloud/package-exclusions into the new group as its last page, and add a warning that package rules replace it. Dissolve the "Policy & Risk" group: governance/cloud/malware-analysis moves into the "SafeDep Cloud" group. No URL changes. Add Cloud Policy cards to the Visibility & Governance and SafeDep Cloud landing pages, and a cloud policy section to the GitHub App and Bitbucket app pages. The GitHub App page no longer says that the app enforces policy as code. In concepts/policy-revisions, state that a setting with no value on one side of a change counts as a change that loosens, as the change direction code does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
Add package-security/pmg/cloud-policy to the Install-Time Package Blocking group. It tells how to turn on cloud.policy on one machine and with MDM, what PMG fetches and caches, what PMG does offline or when a fetch fails, and which PMG settings the cloud policy changes. Add a note to the dependency cooldown page on when the cloud value wins. Add a snippet to the MDM overview, Jamf, JumpCloud and Intune pages that tells IT to set cloud.policy in the managed config and to keep the cooldown keys out of it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
Add reference/cloud-policy-settings (each setting, its type, values, default and enforcing tool, the YAML document and the package rule fields) and reference/cloud-policy-limits (limits, roles, retention, API key access and the accepted gaps) to Reference > Query & Policy. Add a line at the top of reference/policy-as-code and reference/exceptions that separates them from the cloud policy. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
docs-ia.md: update the tab table, R4, the placement table and the page map in section 7. Add three placement rules: a page that changes a cloud policy setting, package rule or policy module goes to Visibility & Governance > Cloud Policy; a page that sets up a tool that enforces the policy goes to the outcome tab of that tool, with a card from Cloud Policy; an independent capability that the policy only references gets its own group. The "Policy & Risk" group no longer exists. The total of section 7 is now counted from docs.json (116 pages); the old total of 89 was stale. CLAUDE.md and the writing-safedep-docs skill: the same placement rows and the new list of concepts. products.md: add a Cloud Policy card and the facts that a review of the source found. The R4 lines that this change touches use a colon instead of a dash. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
- Quickstart and the PMG page: tell the user what to do when
`pmg config set cloud.policy true` prints `key not found`. pmg adds a
missing template key only when the `cloud` section exists
(templateScalarDefault in config/yaml_set.go). Otherwise
`pmg setup install` merges the missing template keys, or the user adds
the key with `pmg config edit`.
- Trust a package: "no longer applies" replaces "stops to apply".
- A trust entry with the scope `vulnerability` is "Not applicable" in
PMG on every page.
- One home for duplicated text: the known gaps live in
reference/cloud-policy-limits, the notice rules in
concepts/policy-revisions, and the trust scope table in
reference/cloud-policy-settings. Other pages link to them.
- Concept pages no longer give command procedure: the sync procedure
moves to target-a-group ("If the publish stops"), the rollback command
stays in roll-back-a-change, and the --selector syntax moves to
target-a-group.
- Quickstart: "changes from" replaces "goes from".
- PMG page: the background fetch runs after each command, also a
blocked one (exit hook in main.go).
- Malicious Package Exclusions: name the Team and Enterprise plans
(FEATURE_PACKAGE_EXCLUSIONS_MANAGEMENT in billing_tier.go) instead of
"Pro and above".
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
SafeDep Report SummaryNo dependency changes detected. Nothing to scan. This report is generated by SafeDep GitHub App |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
…kstart The SafeDep CLI now opens the policy settings document with every field as a commented line, with its allowed values and its value now. The quickstart said only that the document opens, so a new admin did not know how to set a field. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 93cc5d0a07
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The package rules concept said that an old PMG blocks more, never less. That is true only for trust entries. Such a PMG also gets no block entries, so a block entry does not stop an install there, and an admin could count on it during an incident. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz
The filter --applied-revision lists only the endpoints that apply an older revision. An endpoint that applies no cloud policy reports no revision, so the filter does not list it. The Policy column shows - for such an endpoint. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MhRi597EX9odoSDXbVBsxz



Summary
This PR adds the docs for SafeDep Cloud Policy, the MVP of cloud policy management (safedep/control-tower#1592, part of safedep/control-tower#1571). A customer on the Team or Enterprise plan can publish a first policy with these docs and the SafeDep CLI alone.
Merge for dogfooding. control-tower and apiguard are deployed with the policy work. The SafeDep team follows these docs for its own tests before the CLI and pmg releases ship. Until then:
claude/pensive-sagan-3x8any,make build);claude/pensive-sagan-3x8any,make pmg).Two links point to content that is only on those branches until they merge: the CLI command pages in
docs/cmdof safedep/cli, and thecloud.policysection ofdocs/config.mdin safedep/pmg.No URL changes, so the PR adds no redirects.
Structure
Get Started › Core Concepts › Policy (new nested group)
concepts/policyis rewritten with the same URL. It separates the cloud policy (one per tenant, in SafeDep Cloud, enforced by pmg and the pull request checks) from policy as code (vet filter suites with CEL).concepts/policy-resolution: the default policy, the policy base, policy overrides, and the resolved policy.concepts/labels: labels on endpoints and projects, and selectors.concepts/package-rules: block and trust entries.concepts/policy-revisions: policy changes, the preview, the change direction, notices and rollback.concepts/celmoves into this group with the same URL.Visibility & Governance › Cloud Policy (new group, after SafeDep Cloud)
governance/cloud/policy/overviewis the landing page. It lists which tool enforces which setting.governance/cloud/package-exclusionsmoves into this group with the same URL, under a deprecation warning that points to trust entries (safedep/control-tower#1586).governance/cloud/malware-analysismoves into the SafeDep Cloud group.Package Security
package-security/pmg/cloud-policycovers:cloud.policyswitch andglobal_lockdown;dependency-cooldowngets a note that the cloud value can win.Reference › Query & Policy
reference/cloud-policy-settings: each setting path, its value in the default policy, and the tool that enforces it. It links tobuf.build/safedep/api.reference/cloud-policy-limits: the limits, the retention, the known gaps, and what a holder of the tenant API key can read.policy-as-codeandexceptionsget one line that separates them from the cloud policy.Other edits
docs-ia.md,CLAUDE.mdand the skill: a policy setting, package rule or policy module goes to Cloud Policy. A tool that enforces the policy goes to that tool's tab. A capability with its own data and workflow, such as a future catalog of approved components, gets its own group.How the facts were checked
Every command, flag, setting path, default value, limit and behaviour was checked against the source. Nothing comes from the spec or from memory.
main:services/tenantpolicy,policygate,platform/auditand the glossarypolicy/matchin safedep/dryThe docs follow the code where it differs from the specs:
The owner's dogfooding run on 2026-11-05 checked the quickstart flow against production: policy show, edit, publish, a pull request check that failed on a medium vulnerability through a policy override, and the notice email.
Review
A separate review checked more than 40 claims against the source and walked the quickstart as a new Team-plan admin. It found two blocking issues, and a later commit fixes them:
pmg config set cloud.policy trueprintskey not foundon a config with nocloud:section. The docs now give the fix: runpmg setup install, or usepmg config edit.The same commit removes duplicated text, moves CLI detail out of the concept pages, and confirms three claims in the source. The last commit describes the commented fields that
safedep policy editnow shows.Checks
bunx -b mintlify broken-links: only the three existingessentials/failures remain.Generated by Claude Code