Hydra is a Continuous Integration service for Nix based projects.

Note: The instructions provided below are intended to enable new users to get a simple, local installation up and running. They are by no means sufficient for running a production server, let alone a public instance.

Running Hydra is currently only supported on NixOS. The hydra module allows for an easy setup. The following configuration can be used for a simple setup that performs all builds on localhost (Please refer to the Options page for all available options):

{
  services.hydra = {
    enable = true;
    hydraURL = "http://localhost:3000";
    notificationSender = "hydra@localhost";
    useSubstitutes = true;
  };
}

Once the Hydra service has been configured as above and activated, you should already be able to access the UI interface at the specified URL. However some actions require an admin user which has to be created first:

$ su - hydra
$ hydra-create-user <USER> --full-name '<NAME>' \
    --email-address '<EMAIL>' --password-prompt --role admin

Afterwards you should be able to log in by clicking on "Sign In" on the top right of the web interface using the credentials specified by hydra-create-user. Once you are logged in you can click "Admin -> Create Project" to configure your first project.

In order to evaluate and build anything you need to create projects that contain jobsets. Hydra supports imperative and declarative projects and many different configurations. The steps below will guide you through the required steps to creating a minimal imperative project configuration.

Log in as administrator, click "Admin" and select "Create project". Fill the form as follows:

• Identifier: hello-project
• Display name: hello
• Description: hello project

Click "Create project".

After creating a project you are forwarded to the project page. Click "Actions" and choose "Create jobset". Change Type to Legacy for the example below. Fill the form with the following values:

• Identifier: hello-project
• Nix expression: examples/hello.nix in hydra
• Check interval: 60
• Scheduling shares: 1

We have to add two inputs for this jobset. One for nixpkgs and one for hydra (which we are referencing in the Nix expression above):

• Input name: nixpkgs

• Type: Git checkout

• Value: https://github.com/NixOS/nixpkgs nixos-24.05

• Input name: hydra

• Type: Git checkout

• Value: https://github.com/nixos/hydra

Make sure State at the top of the page is set to "Enabled" and click on "Create jobset". This concludes the creation of a jobset that evaluates ./examples/hello.nix once a minute. Clicking "Evaluations" should list the first evaluation of the newly created jobset after a brief delay.

You can build Hydra via nix-build using the provided default.nix:

$ nix build

You can use the provided flake to get a working development environment:

$ nix develop

The development environment can also automatically be established using nix-direnv.

When working on new features or bug fixes you need to be able to run Hydra from your working copy. This can be done using foreman:

$ nix develop
$ # hack hack
$ ninja -C build
$ cargo build
$ foreman start

Have a look at the Procfile if you want to see how the processes are being started. In order to avoid conflicts with services that might be running on your host, hydra and postgress are started on custom ports:

• hydra-server: 63333 with the username "alice" and the password "foobar"
• postgresql: 64444, can be connected to using psql -p 64444 -h localhost hydra

Note that this is only ever meant as an ad-hoc way of executing Hydra during development. Please make use of the NixOS module for actually running Hydra in production.

The following users can authenticate via Kanidm:

• andy with password kanidm credential (Hydra admin)
• bert with password kanidm credential (Hydra user)

After making your changes, verify the test suite passes and perlcritic is still happy.

Start by following the steps in Development Environment.

Then, you can run the Perl tests and perlcritic together with:

$ nix develop
$ meson test -C build

You can run a single Perl test with:

$ nix develop
$ cd build
$ meson test --test-args=../t/Hydra/Event.t testsuite

And run just perlcritic with:

$ nix develop
$ cd build
$ meson test perlcritic

And run the Rust tests with:

$ nix develop
$ cargo test

You can also interface with Hydra through a JSON API. The API is defined in hydra-api.yaml and you can test and explore via the swagger editor

• Hydra User's Guide
• Hydra on the NixOS Wiki
• hydra-cli
• Peter Simons - Hydra: Setting up your own build farm (NixOS)

Hydra is licensed under GPL-3.0

Icons provided free by EmojiOne.