> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safedep.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Target a Group of Endpoints or Projects

> Label endpoints and projects, then write a policy override that sets other policy values for them.

A policy override sets other values for the endpoints and projects that its label selector matches. This guide labels a group, writes a policy override for it, and checks the result. For the rules of resolution, see [Policy Resolution](https://docs.safedep.io/concepts/policy-resolution.md) and [Labels](https://docs.safedep.io/concepts/labels.md).

> [!NOTE]
>
> This guide needs the SafeDep Cloud Team or Enterprise plan and the Admin role. See [pricing](https://safedep.io/pricing).

## Choose the labels

Each subject already has some labels:

* An endpoint with PMG has `reported/os` and `reported/arch`, such as `reported/os=darwin`.
* A project that is bound to a repository has `scm/forge`, `scm/owner` and `scm/repo`.

For any other group, set a `custom/` label. For a policy override that loosens the policy, select on `custom/`, `scm/` or `safedep.io/` labels only. An endpoint sends its own `reported/` labels, so SafeDep Cloud cannot check them.

## Label projects

1. Find the projects. A repository is a project:

   ```bash theme={null}
   safedep project list --source github
   ```

   If a repository is not in the list, create its project with `safedep project sync OWNER/REPOSITORY`.

2. Set the label on each project, by its exact name:

   ```bash theme={null}
   safedep project label set acme/payments-api acme/ledger --label custom/criticality=high
   ```

## Label endpoints

1. Find the endpoints:

   ```bash theme={null}
   safedep endpoint list --search laptop
   ```

2. Set the label. An endpoint is its id, a unique prefix of the id, or a hostname that `safedep endpoint list` showed:

   ```bash theme={null}
   safedep endpoint label set arjuns-mbp --label custom/team=release
   ```

A label change makes no policy revision. It applies at the next policy fetch of each endpoint, and at the next pull request check of each project.

## Write the policy override

1. Open the policy settings document:

   ```bash theme={null}
   safedep policy edit -m "payments: fail on medium"
   ```

2. Add a policy override under `overrides`:

   ```yaml theme={null}
   overrides:
     - name: payments
       priority: 200
       description: Stricter gate for payment services (CUST-412)
       selector:
         matchLabels: {custom/criticality: high}
       spec:
         scan_gate:
           fail_on: medium
         package_admission:
           cooldown:
             min_age: 7d
   ```

   * `name` uses lowercase letters, digits and hyphens. Each name is unique.
   * `priority` is a number from 1 to 1,000,000. Each priority is unique. When two policy overrides match a subject and set one field, the higher priority wins.
   * `spec` holds only the fields that the policy override changes.
   * Leave out `id` for a new policy override. The server sets it. Keep the `id` of an existing policy override when you edit or rename it.

   A selector can also use `matchExpressions`, with the operators `In`, `NotIn`, `Exists` and `DoesNotExist`:

   ```yaml theme={null}
       selector:
         matchExpressions:
           - {key: reported/os, operator: In, values: [darwin, linux]}
           - {key: custom/team, operator: Exists}
   ```

3. Save the file and close the editor.

4. Preview and publish the change that the command created:

   ```bash theme={null}
   safedep policy change show 18
   safedep policy change publish 18 -m "payments: fail on medium"
   ```

   Use the change number that `safedep policy edit` printed. A new policy override counts as a change that loosens, because it can move subjects to a looser result. So the publish asks you to confirm it.

## Check the result

Before you publish, list the subjects that the selector matches:

```bash theme={null}
safedep project list --selector custom/criticality=high
safedep endpoint list --selector custom/criticality=high
```

`--selector` takes the selector as text. Separate the terms with commas, as in `custom/team=release,reported/os=darwin`. Every term must hold. A term can be `key=value`, `key!=value`, `key in (a,b)`, `key notin (a,b)`, `key` or `!key`.

After you publish, show the policy of one subject and the layer that set each value:

```bash theme={null}
safedep project policy show acme/payments-api --field scan_gate.fail_on
```

## If the publish stops

When another Admin published a change to the policy settings after you created your change, the publish stops, because your change is stale. Sync the change, read the preview again, and publish:

```bash theme={null}
safedep policy change sync 18
safedep policy change show 18
safedep policy change publish 18 -m "payments: fail on medium"
```

The sync moves the base of the change to the head revision and keeps your settings as you wrote them. Your settings can undo the change of the other Admin, so read the preview before you publish.

## Select one endpoint for a short time

A selector can name one endpoint by `safedep.io/endpoint-id`. Such a policy override needs an expiry:

```yaml theme={null}
overrides:
  - name: debug-arjun
    priority: 900
    description: No cooldown on one laptop while we debug a build (S-102)
    expires_at: 2026-12-01T00:00:00Z
    selector:
      matchLabels: {safedep.io/endpoint-id: 01KR0EKN6PMW0ZRFRN992H1PKX}
    spec:
      package_admission:
        cooldown:
          min_age: 0s
```

The selector takes the full endpoint id that `safedep endpoint list --output json` shows. After its expiry, the policy override matches no subject.

## Next steps

> [card] [Fail Pull Request Checks](https://docs.safedep.io/governance/cloud/policy/pull-request-checks.md)
>
> Use a policy override on the scan gate of a group of projects.

> [card] [Set a Cooldown](https://docs.safedep.io/governance/cloud/policy/set-a-cooldown.md)
>
> Set the cooldown for a group of endpoints.

> [card] [Labels](https://docs.safedep.io/concepts/labels.md)
>
> Prefixes, sources and selectors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.