Skip to content

Artefacts

Build outputs can offer files for download, and a fixed link can point to the newest build of a task.

Requirements:

  • A task with a wildcard matching the package.
  • An API key for links into a private project.

1. Declare the Files

Builds list their downloadable files in $out/nix-support/hydra-build-products, in the Hydra format.

# package.nix
postInstall = ''
  mkdir -p $out/nix-support
  echo "file binary-dist $out/bin/gradient" >> $out/nix-support/hydra-build-products
'';
Field Example Meaning
Type file, doc Kind of the file, shown as a badge
Subtype binary-dist, html Finer kind. HTML files open in a new browser tab
Path $out/bin/gradient File or directory inside the output
  • Lines name a file each, with the three fields separated by spaces.
  • Directories download as a <name>.tar.zst archive.

2. Find the Artefacts

Open the task, then the menu of an entry point, then Artefacts. Entry points with files show a box icon. Menu entries for unfinished builds appear disabled.

Rows on the Build Artefacts page show the type, name and size of each file, next to a Download or Open button.

gradient download

The CLI can pick the evaluation and the files interactively.

Fixed links read the newest evaluation of a task.

https://gradient.example.com/api/v1/tasks/<project>/<task>/entry-point-downloads?eval=<attribute>&filename=<file>
Parameter Value
<project>, <task> Names of the project and the task
eval Attribute path of the entry point, such as packages.x86_64-linux.gradient-cli-static. URL-encode " as %22
filename File name from hydra-build-products, such as gradient
token Optional API key for a private project

Real-world example from the Gradient CLI install.

curl -fLo gradient "https://public.gradient.ci/api/v1/tasks/gradient/main/entry-point-downloads?eval=packages.x86_64-linux.gradient-cli-static&filename=gradient"
  • Links to an unchanged derivation keep working during a new evaluation.
  • Links to a changed derivation return 404 until the new build is done (Completed or Substituted). Downloads from the previous build remain unavailable meanwhile.
  • Markdown pages can embed the link as a button: [Download](<link>){ .md-button }.

4. Share Private Files

Public projects need no credentials. Private projects offer two kinds of links.

Link Lifetime Use
entry-point-downloads?...&token=GRAD... Until the API key expires Fixed links for scripts and deployments
/builds/<build>/download/<file>?token=<token> 1 hour Sharing a file of a specific build
  • Create a dedicated API key for fixed links, pinned to the project, with viewProject only and allowed_ips where possible.
  • Request the 1-hour token from GET /builds/<build>/download-token. Links on the Build Artefacts page include this token already.

Warning

Tokens in a URL end up in shell histories and proxy logs. Prefer the 1-hour token for links shared with people.

Verify Deployment

curl -fsSI "https://gradient.example.com/api/v1/tasks/<project>/<task>/entry-point-downloads?eval=<attribute>&filename=<file>"

Working links answer 200 with a Content-Disposition header naming the file.

Next Steps