Overview¶

Getting Started¶

Register / Log in - / redirects to login automatically.
Create an organization - organizations own projects, caches, and workers.
Create a project - point it at a Git repository and set an evaluation wildcard.
Configure a worker - at least one gradient-worker must be connected to run jobs. Deploy one co-located on the server or on a dedicated build machine (see Workers below).

Evaluation Wildcard¶

The wildcard is a dot-separated Nix attribute path selecting which flake outputs to build. Multiple patterns are separated by commas (no spaces). The root level is restricted to: checks, packages, formatter, legacyPackages, nixosConfigurations, devShells, hydraJobs.

Two wildcard tokens expand attribute names at a given level:

Token	Behaviour
`*`	Recursive - matches all attribute names at this level and, at the trailing position, descends one additional level. Consecutive `` segments collapse: `packages..` and `packages.` are equivalent.
`#`	Non-recursive - matches all attribute names at this level but collects only those where `type == "derivation"`. Does not descend further. Use this to target a specific depth precisely.

`*` vs `#`¶

packages.x86_64-linux.*   # finds packages.*.*.*  - recurses past x86_64-linux into each package
packages.x86_64-linux.#   # finds packages that are derivations directly under x86_64-linux, no deeper

In practice * is the right choice for almost all flakes. Use # when a flake nests attrsets inside a package attribute and you do not want those nested attrs collected.

Exclusions¶

Prefix a pattern with ! to remove matching paths from the set built by the preceding include patterns.

packages.*,!packages.x86_64-linux.broken

Exclusion patterns must be exact paths - they cannot contain * or #.

Examples¶

Wildcard	What gets built
`packages.x86_64-linux.#`	Every derivation directly under `packages.x86_64-linux`
`packages.x86_64-linux.*`	Same, but also recurses one level deeper into nested attrsets
`packages.#.#`	Every derivation at exactly depth 2 under `packages` (system → package) across all systems - first `#` expands systems, second `#` expands packages non-recursively
`checks.x86_64-linux.*`	All checks for x86_64-linux
`packages.*`	Packages for every system (equivalent to `packages..`)
`packages.,checks.`	Packages and checks for every system
`packages.x86_64-linux.,checks.x86_64-linux.`	Packages and checks for x86_64-linux only
`nixosConfigurations.#.config.system.build.toplevel`	All NixOS system configurations
`devShells.*`	All dev shells for every system
`*`	Everything in all top-level output categories
`packages.*,!packages.x86_64-linux.broken`	All packages except one excluded path

Evaluations¶

Click Start Evaluation on the project page. Gradient clones the repo, evaluates each wildcard match, and dispatches the resulting derivations to connected workers.

The evaluation log page shows per-build status, combined ANSI build output, and an Abort button.

Evaluations can also be triggered automatically:

GitHub App - when the App is installed, push events from GitHub trigger evaluations instantly (no polling). See GitHub App.
Forge webhooks - for Gitea, Forgejo, GitLab, or GitHub without the App, configure a per-org push webhook. See Forge Webhooks.
Polling - fallback for projects without webhook configuration; Gradient checks for new commits every 60 seconds.

Members & Roles¶

Each organization manages its own members and roles under Organization → Settings → Members & Roles.

Built-in roles¶

Every organization carries the same three immutable system roles:

Role	What it can do
Admin	Everything: full settings, member & role management, project lifecycle, organization deletion.
Write	Create/edit projects, manage webhooks/integrations/workers/cache subscriptions, trigger evaluations.
View	Read members-only content; mutate non-secret sub-resources only (workers, integrations, cache subs, SSH key).

Built-in roles cannot be edited or deleted.

Custom roles¶

Members holding the manageRoles capability can create org-specific custom roles by ticking individual permissions:

Org-level: viewOrg, manageOrgSettings, deleteOrg, manageMembers, manageRoles, manageIntegrations, manageWebhooks, manageWorkers, manageSubscriptions, manageSshKey.
Project-level: createProject, editProject, triggerEvaluation.

Permission identifiers and their canonical order are returned by GET /api/v1/orgs/{organization}/roles's available_permissions field - new capabilities are appended over time and the UI picks them up automatically.

A role currently assigned to one or more members cannot be deleted; reassign the affected members first.

SSH Keys¶

Each organization has one Ed25519 SSH key pair, generated automatically. The public key is shown in Organization → Settings → SSH.

Add this key to your Git hosts as a deploy key so Gradient can clone private repositories.

The key is scoped to the organization; different organizations use different keys.

Workers¶

Build capacity is provided by gradient-worker processes. The server does not start a worker automatically - at least one must be configured explicitly.

To run a worker on the server host itself, enable services.gradient.worker. Workers authenticate using per-organization tokens. A worker authorized for an org receives only that org's job offers.