Scopes

Scopes control what actions an account can perform on which resources. Understanding the scope system is key to setting up the right access for developers, machines, and automated pipelines.

Scope Fields

Each scope has four fields:

Field	Description	Valid values
`effect`	Whether to allow or deny the matched request	`allow`, `deny`
`action`	The operation being performed	`read`, `write`, `delete`, `*`
`resource`	The type of resource being accessed	`artifacts`, `repos`, `groups`, `members`, `tokens`, `org`, `*`
`filter`	A glob pattern matched against the specific resource name (e.g. repository slug). Use `*` to match all.	`nix-cache`, `nix-`, ``

Examples:

effect: allow, action: read, resource: artifacts, filter: nix-cache — read artifacts from the nix-cache repository
effect: allow, action: write, resource: artifacts, filter: nix-cache — push artifacts to nix-cache
effect: allow, action: read, resource: artifacts, filter: * — read access to all repositories
effect: deny, action: write, resource: artifacts, filter: prod-* — deny writes to any repository whose name starts with prod-

How Scopes Are Assigned

Scopes are assigned to groups, not directly to individual accounts. An account inherits scopes from every group it belongs to. The effective set of permissions is the union of all scopes across all group memberships.

Account A  ──belongs to──▶  group:nix-readers      (allow read  artifacts nix-cache)
           ──belongs to──▶  group:release-managers  (allow read  artifacts *
                                                      allow write artifacts releases)

Effective scopes for Account A:
  allow read  artifacts nix-cache
  allow read  artifacts *
  allow write artifacts releases

Deny rules are evaluated before allow rules — if any matching scope has effect: deny, the request is rejected regardless of other allows.

Special Groups

`@everyone`

Every member of an organization is automatically a member of @everyone. Scopes assigned to @everyone apply to all org members. Use this group to set organization-wide defaults, such as read access to shared public repositories.

`@owners`

Organization owners are automatically added to @owners, which grants full administrative access to the organization, including managing members, groups, repositories, and settings. The @owners scope set is immutable and cannot be edited.

Worked Examples

1. Read-Only Configuration

For consumers that only pull artifacts and never push:

Group: nix-readers
Scope: effect: allow, action: read, resource: artifacts, filter: nix-cache
Use case: NixOS machines that use the binary cache as a substituter but have no need to push build results.

2. Read-Write Configuration

For developers or CI pipelines that both pull and push:

Group: nix-contributors
Scopes:
- effect: allow, action: read, resource: artifacts, filter: nix-cache
- effect: allow, action: write, resource: artifacts, filter: nix-cache
Use case: Developer machines building locally and uploading to the cache, or a CI pipeline storing build results for downstream consumers.

3. Semi-Admin Configuration

For release engineers who need broad read access but write access only to production repositories:

Group: release-managers
Scopes:
- effect: allow, action: read, resource: artifacts, filter: *
- effect: allow, action: write, resource: artifacts, filter: releases
- effect: allow, action: write, resource: artifacts, filter: apt-stable
Use case: Release engineers who need to inspect any repository but should only be able to publish artifacts to the releases and apt-stable repositories.