Overview¶

Getting Started¶

Register / Log in - / redirects to login automatically.
Create a project - projects own tasks, caches, and workers.
Create a task - 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 task 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-project push webhook. See Forge Webhooks.
Polling - fallback for tasks without webhook configuration; Gradient checks for new commits every 60 seconds.

Members & Roles¶

Each project manages its own members and roles under Project → Settings → Members & Roles.

Built-in roles¶

Every project carries the same three immutable system roles:

Role	What it can do
Admin	Everything: full settings, member & role management, task lifecycle, project deletion.
Write	Create/edit tasks, 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 project-specific custom roles by ticking individual permissions:

Project-level: viewProject, manageProjectSettings, deleteProject, manageMembers, manageRoles, manageIntegrations, manageWebhooks, manageWorkers, manageSubscriptions, manageSshKey.
Task-level: createTask, editTask, triggerEvaluation.

Permission identifiers and their canonical order are returned by GET /api/v1/projects/{project}/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.

Appearance¶

Settings -> Profile -> Appearance picks the colour theme: System, Light or Dark. It applies as soon as you choose it.

System follows the operating system's prefers-color-scheme setting and keeps following it, so a machine that switches to dark at sunset switches Gradient with it. Light and Dark pin the choice regardless of the OS.

The preference lives in the browser's local storage rather than on your account, so it is per browser: a second device starts on System until it is set there too. Clearing site data returns it to System.

SSH Keys¶

Each project has one Ed25519 SSH key pair, generated automatically. The public key is shown in Project → 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 project; different projects 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-project tokens. A worker authorized for a project receives only that project's job offers.