Policies

Policies let administrators control how Depotex behaves in their organization. A policy watches one kind of action (an event, such as a repository being created), checks a condition, and then blocks the action, lets it through with a warning, or adjusts one of its values.

License: Pro or higher. Permissions: policies:read to view, policies:write to create and change, policies:admin to exempt users or roles. Organization admins can view and write policies; exemptions need a super admin.

1. Create a policy

This example limits sign-ins to your office and VPN networks. Every policy is made the same way: pick a template (or write a condition), test it, start it in dry run, then enforce it once its decisions look right.

Screenshot needed

policies-create.gif

Creating a policy: New policy, a template, its networks, Try it, then Create policy

1. Open the policies — Go to Settings → Policies and select New policy. You need the policies:write permission (organization admins and super admins have it).
2. Pick a template — Templates are grouped by area: Sign-in, API tokens, Profiles, Repositories and Other. The badge on each says what it does when it matches: Block, Warn or Adjust. Choose Sign in only from these networks. For a rule no template covers, choose Custom condition under Your own at the end of the list (see Conditions).
3. Fill in the form — Give the policy a Name and an optional Description. Under Allowed IP ranges, enter one range per line, for example 10.0.0.0/8 and 192.168.0.0/16. Leave Message shown to the user empty to show the standard message in each person's language, or write your own (for example where to find the VPN).
4. Set the priority — Priority decides the order when several policies watch the same event: lower numbers run first and the first policy that blocks wins (default 100). See Order and conflicts.
5. Choose how it starts — Under Start in, keep Dry run (Recommended): the policy records what it would do without stopping anyone. Enforced applies it at once; Off saves it without running it.
6. Test it — In Try it, edit the Sample payload (for example set ip to an address outside your ranges), set Actor roles if the condition uses them, and select Run test. The result says whether the condition matches and what the policy would do. Nothing is saved.
7. Create it — Select Create policy. The policy opens on its own page with the tabs Settings, Decisions, Compliance, History and Exemptions, and the mode switch (Off, Dry run, Enforced) at the top.
8. Watch, then enforce — Leave it in dry run for a few days and check Decisions for sign-ins it would have blocked. Add exemptions for accounts that must keep working (for example a break-glass admin), then select Enforced. Depotex asks first and says how many actions it would have affected in the last 7 days.

Screenshot needed

policies-new.png

New policy: templates grouped by area, each with the effect it has

Screenshot needed

policies-try-it.png

Try it: a sample sign-in from outside the ranges matches, so the policy would block it

Screenshot needed

policies-created.png

The new policy in dry run, with its Settings, Decisions, Compliance, History and Exemptions tabs

2. Managing policies

Go to Settings → Policies. The list shows each policy's event, effect, mode and priority, and what it did in the last 7 days (for example "3 blocked" or "4 would warn"); filter it by mode with All, Enforced, Dry run and Off. Open a policy to edit it, see its decisions, restore an earlier version, or manage exemptions.

Screenshot needed

policies-list.png

Settings → Policies: each policy's event, effect, mode, priority and decisions in the last 7 days

• New policy: templates are grouped by area (Sign-in, API tokens, Profiles, Repositories); pick one and fill in its form, or choose Custom condition under Your own to write your own: choose the event, write the condition (the fields you can use are listed under the event), choose what happens, and write the message people see. Start in sets the first mode; dry run is recommended.
• Mode: switch an existing policy between Off, Dry run and Enforced at the top of its page. Enforcing asks first and says how many actions it would have affected in the last 7 days.
• Try it: in the policy's settings, run the condition against sample data to see whether it would match, without saving. Changes wait in a bar at the bottom until you save or discard them.
• Decisions: what the policy blocked, warned about, adjusted, or would have in dry run.
• History: every saved version with what it changed (for example "Added 192.168.12.0/24 to Allowed IP ranges"), who saved it and when; Restore saves an older one as the newest version.
• Exemptions: users or roles the policy skips (super admins only).

When a warn policy matches, people see its message as a notice in the corner of the screen; when a block policy matches, they see its message instead of the action happening.

3. Templates

Templates cover common rules without writing a condition. Pick one under New policy, fill in its form, and Depotex builds the condition for you. The message people see is a standard one, translated into each person's language; write your own message to replace it.

Screenshot needed

policies-editor.png

A policy made from a template: its rule, effect, message and priority

The SBOM and vibe templates are listed under Other; see SBOMs & vulnerabilities and Quarantine for what a quarantined version means. Turn off “Remember me” adjusts the sign-in instead of blocking it; every other template blocks.

A policy made from a template opens in the same form when you edit it. Switch to custom condition turns it into a custom policy, starting from the condition the template built.

4. What a policy can do

Policies only restrict: they never let anyone do something their role doesn't already allow.

5. Modes

Start every policy in dry run, check its decisions for a few days, then switch it to enforce.

6. Conditions

Conditions are short expressions in CEL (Common Expression Language). They can use:

!(payload.format in ["raw", "npm"])                 // anything other than raw or npm
!payload.name.startsWith("team-")                   // names must start with team-
!("org_admin" in actor.roles) && payload.format == "docker"

Sign-on policies use auth.login, checked after the password is verified and before the session starts:

!payload.ip.startsWith("10.20.")                    // only from the office network
payload.remember_me                                   // with effect "set" {"remember_me": false}: no long sessions
payload.expires_at == null                            // on apitoken.create: tokens must expire

A condition must be true or false, may only use the fields the event provides (checked when you save), and has a size limit so it always runs quickly. GET /api/policies/events lists the events that accept policies and their fields.

7. Order and conflicts

• Policies run in order of priority (lower first).
• The first enforced block stops the action; warnings from all matching policies are shown.
• If two policies adjust the same field, the one with the lower priority wins.
• If a policy's condition fails to run, the action goes ahead, except on security-sensitive actions, where it is blocked.

8. Events that accept policies

auth.login, apitoken.create, apitoken.update, apitoken.rotate, apitoken.org_policy.update, avatar.update, alert.create and, in the sample app, depot.repository.create. See the Events reference.

9. Exemptions

Exempt a user (user:42) or a role (role:org_admin) from a policy, with a reason and an optional expiry date. Exemptions are logged, like every policy change.

10. Compliance: checking what already exists

A policy only checks actions when they happen, so things created before it existed never meet it — for example API tokens created before a 90-day limit. The policy's Compliance tab lists existing items that the policy would block or warn about if they were created today.

• Depotex checks every block and warn policy that is on each night; Check now runs it immediately (needs policies:write).
• It only reports. Nothing is changed, revoked or deleted: decide what to do with each item yourself.
• Each item is checked with its owner as the actor, and exemptions apply.
• Available for API tokens and repositories. Sign-in policies can't be checked this way (there's nothing lasting to check).
• A check reads at most POLICY_SCAN_MAX_ITEMS items (10,000 by default) and is marked as incomplete beyond that.

11. Decisions and history

• Every time a policy blocks, warns, adjusts, would have done so in dry run, is skipped by an exemption or fails, a decision is recorded (kept 30 days, POLICY_DECISION_RETENTION_DAYS).
• Every change creates a new version; you can roll back to any earlier version.

12. Performance

• An action with no policies for your organization isn't slowed down.
• Each policy on an event is checked while the user waits, in well under a millisecond for typical conditions; the total is capped by POLICY_EVAL_BUDGET (50 ms by default).
• Every time a policy matches, a decision is written to the database. A policy that matches almost everything on a busy event — for example a dry-run policy with condition true on auth.login — writes a decision for every sign-in. Keep conditions specific and don't leave broad dry runs running.
• Changes to policies take effect immediately on all servers with Redis, and within POLICY_CACHE_TTL (10 s) without it.

13. API

curl -X POST /api/policies -H "Content-Type: application/json" -d '{
  "name": "Only raw and npm repositories",
  "event": "depot.repository.create",
  "mode": "dry_run",
  "condition": "!(payload.format in [\"raw\", \"npm\"])",
  "effect": "deny",
  "messageText": "Only raw and npm repositories are allowed."
}'

From a template: send template and templateParams instead of event, condition and effect. Parameter errors come back as fields named templateParams.<name>.

curl -X POST /api/policies -H "Content-Type: application/json" -d '{
  "name": "Tokens expire within 90 days",
  "template": "token_max_lifetime",
  "templateParams": {"days": 90}
}'

A blocked action returns 403 with "reason": "policy_denied". Warnings come back in the Depotex-Policy-Warnings response header (base64url-encoded JSON).

14. Settings