Permissions and access model

Reference for Craftifact roles, repository permissions, groups, robot accounts, and token scopes.

How access is assembled

Craftifact access starts in the instance configuration. Roles contain repository permissions, and role_assignments bind those roles to users or groups. Groups can be based on explicit members, mail domains, or identity-provider groups.

Robot accounts use the same role model as human users. Their owners decide who may mint or rotate the robot token, while the robot account’s roles decide what the token can do after authentication.

API tokens and robot tokens also carry package-family scopes. Those scopes are an additional package-route gate for families such as Maven, Python, npm, OCI, and Go; they do not replace repository permissions. A token needs both a matching package-family scope and the required repository permission.

Permission syntax

Repository permissions use this form:

<repository>:<domain>:<action>

Examples:

libs-release:artifact:read
containers:findings:suppress
oci:pull_gate:override

Wildcards are supported:

<repository>:*:* grants every domain and action in one repository.
<repository>:artifact:* grants every artifact action in one repository, but not findings, composition, license-policy, or pull-gate actions.
"*:*:*" grants every repository-scoped permission and must be quoted in YAML.

Legacy permissions such as artifact:add, artifact:exec_elevated, artifact:manage_findings, artifact:manage_licenses, artifact:manage_policies, and sbom:* are no longer accepted.

Available permissions

Permission	Meaning
`artifact:read`	Read package artifacts, package metadata, repository browse data, and artifact details for the selected repository.
`artifact:publish`	Upload or publish new package artifacts to a writable hosted repository.
`artifact:redeploy`	Upload again under an existing package coordinate when the repository allows redeploy.
`artifact:delete`	Delete artifacts or package content where the repository type supports deletion.
`composition:read`	Read SBOM-derived composition data, dependency views, license component views, and composition-backed evidence summaries.
`composition:override_limits`	Create durable overrides for SBOM generation limits when a subject needs unbounded analysis.
`findings:read`	Read vulnerability, secret, and suppression surfaces for findings on the selected repository.
`findings:suppress`	Create, renew, revoke, and manage vulnerability suppressions, including detailed suppression management fields.
`license_policy:read`	Read license-policy status, component license results, and license-policy decisions for the selected repository.
`license_policy:configure`	Configure repository license policies when user-managed policy configuration is enabled.
`pull_gate:read`	Read pull-gate state that affects package discovery and retrieval.
`pull_gate:inspect`	Inspect pull-gate decisions, held artifacts, decision logs, and evidence-relevant policy state.
`pull_gate:override`	Fast-track or override pull-gate holds where the policy allows user action.

Some read flows combine several domains. For example, least-privilege evidence collection needs artifact read access, composition read access, findings read access, license-policy read access, pull-gate inspect access, and a matching token scope for every selected repository family.

Common role shapes

Use the smallest role shape that matches the workflow. These examples show intent; adapt repository names to your instance.

roles:
  - name: release-reviewer
    permissions:
      - "libs-release:artifact:read"
      - "libs-release:composition:read"
      - "libs-release:findings:read"
      - "libs-release:license_policy:read"
      - "libs-release:pull_gate:inspect"

  - name: package-publisher
    permissions:
      - "libs-release:artifact:read"
      - "libs-release:artifact:publish"
      - "libs-release:artifact:redeploy"

  - name: vulnerability-triage
    permissions:
      - "libs-release:artifact:read"
      - "libs-release:composition:read"
      - "libs-release:findings:read"
      - "libs-release:findings:suppress"

  - name: policy-manager
    permissions:
      - "libs-release:license_policy:read"
      - "libs-release:license_policy:configure"
      - "libs-release:pull_gate:read"
      - "libs-release:pull_gate:inspect"
      - "libs-release:pull_gate:override"

For automation, assign roles to a robot account and then mint a token with only the package-family scopes the integration needs. For example, a CI job that publishes npm packages should not receive OCI scope unless it also talks to OCI routes.

Practical boundaries

Repository permissions are scoped to repository names. If a role only grants libs-release:artifact:read, it does not grant access to a repository named containers.

Read permissions are domain-specific. artifact:read does not imply findings, composition, license-policy, or pull-gate visibility.

Write-style permissions are also domain-specific. findings:suppress does not grant artifact publish rights, and license_policy:configure does not grant pull-gate override rights.

The read_only repository setting and repository-specific policy settings can still restrict behavior. A user may have artifact:publish, but a read-only repository still blocks writes.