Continuous Integration (GNU Guix Reference Manual)

12.9.26 Continuous Integration

Cuirass is a continuous integration tool for Guix. It can be used both for development and for providing substitutes to others (see Substitutes).

The (gnu services cuirass) module provides the following service.

Scheme Procedure: cuirass-service-type: The type of the Cuirass service. Its value must be a cuirass-configuration object, as described below.

To add build jobs, you have to set the specifications field of the configuration. For instance, the following example will build all the packages provided by the my-channel channel.

(define %cuirass-specs
  #~(list (specification
           (name "my-channel")
           (build '(channels my-channel))
           (channels
            (cons (channel
                   (name 'my-channel)
                   (url "https://my-channel.git"))
                  %default-channels)))))

(service cuirass-service-type
         (cuirass-configuration
          (specifications %cuirass-specs)))

To build the linux-libre package defined by the default Guix channel, one can use the following configuration.

(define %cuirass-specs
  #~(list (specification
           (name "my-linux")
           (build '(packages "linux-libre")))))

(service cuirass-service-type
         (cuirass-configuration
          (specifications %cuirass-specs)))

The other configuration possibilities, as well as the specification record itself are described in the Cuirass manual (see Specifications in Cuirass).

While information related to build jobs is located directly in the specifications, global settings for the cuirass process are accessible in other cuirass-configuration fields.

Data Type: cuirass-configuration

Data type representing the configuration of Cuirass.

cuirass (default: cuirass): The Cuirass package to use.
log-file (default: "/var/log/cuirass.log"): Location of the log file.
web-log-file (default: "/var/log/cuirass-web.log"): Location of the log file used by the web interface.
cache-directory (default: "/var/cache/cuirass"): Location of the repository cache.
user (default: "cuirass"): Owner of the cuirass process.
group (default: "cuirass"): Owner’s group of the cuirass process.
interval (default: 60): Number of seconds between the poll of the repositories followed by the Cuirass jobs.
parameters (default: #f): Read parameters from the given parameters file. The supported parameters are described here (see Parameters in Cuirass).
remote-server (default: #f): A cuirass-remote-server-configuration record to use the build remote mechanism or #f to use the default build mechanism.
database (default: "dbname=cuirass host=/var/run/postgresql"): Use database as the database containing the jobs and the past build results. Since Cuirass uses PostgreSQL as a database engine, database must be a string such as "dbname=cuirass host=localhost".
port (default: 8081): Port number used by the HTTP server.
host (default: "localhost"): Listen on the network interface for host. The default is to accept connections from localhost.
specifications (default: #~'()): A gexp (see G-Expressions) that evaluates to a list of specifications records. The specification record is described in the Cuirass manual (see Specifications in Cuirass).
use-substitutes? (default: #f): This allows using substitutes to avoid building every dependencies of a job from source.
one-shot? (default: #f): Only evaluate specifications and build derivations once.
fallback? (default: #f): When substituting a pre-built binary fails, fall back to building packages locally.
extra-options (default: '()): Extra options to pass when running the Cuirass processes.

Cuirass remote building

Cuirass supports two mechanisms to build derivations.

Using the local Guix daemon. This is the default build mechanism. Once the build jobs are evaluated, they are sent to the local Guix daemon. Cuirass then listens to the Guix daemon output to detect the various build events.
Using the remote build mechanism. The build jobs are not submitted to the local Guix daemon. Instead, a remote server dispatches build requests to the connect remote workers, according to the build priorities.

To enable this build mode a cuirass-remote-server-configuration record must be passed as remote-server argument of the cuirass-configuration record. The cuirass-remote-server-configuration record is described below.

This build mode scales way better than the default build mode. This is the build mode that is used on the GNU Guix build farm at https://ci.guix.gnu.org. It should be preferred when using Cuirass to build large amount of packages.

Data Type: cuirass-remote-server-configuration

Data type representing the configuration of the Cuirass remote-server.

backend-port (default: 5555): The TCP port for communicating with remote-worker processes using ZMQ. It defaults to 5555.
log-port (default: 5556): The TCP port of the log server. It defaults to 5556.
publish-port (default: 5557): The TCP port of the publish server. It defaults to 5557.
log-file (default: "/var/log/cuirass-remote-server.log"): Location of the log file.
cache (default: "/var/cache/cuirass/remote"): Use cache directory to cache build log files.
trigger-url (default: #f): Once a substitute is successfully fetched, trigger substitute baking at trigger-url.
publish? (default: #t): If set to false, do not start a publish server and ignore the publish-port argument. This can be useful if there is already a standalone publish server standing next to the remote server.
public-key
private-key: Use the specific files as the public/private key pair used to sign the store items being published.

At least one remote worker must also be started on any machine of the local network to actually perform the builds and report their status.

Data Type: cuirass-remote-worker-configuration

Data type representing the configuration of the Cuirass remote-worker.

cuirass (default: cuirass): The Cuirass package to use.
workers (default: 1): Start workers parallel workers.
server (default: #f): Do not use Avahi discovery and connect to the given server IP address instead.
systems (default: (list (%current-system))): Only request builds for the given systems.
log-file (default: "/var/log/cuirass-remote-worker.log"): Location of the log file.
publish-port (default: 5558): The TCP port of the publish server. It defaults to 5558.
substitute-urls (default: %default-substitute-urls): The list of URLs where to look for substitutes by default.
public-key
private-key: Use the specific files as the public/private key pair used to sign the store items being published.

Laminar

Laminar is a lightweight and modular Continuous Integration service. It doesn’t have a configuration web UI instead uses version-controllable configuration files and scripts.

Laminar encourages the use of existing tools such as bash and cron instead of reinventing them.

Scheme Procedure: laminar-service-type

The type of the Laminar service. Its value must be a laminar-configuration object, as described below.

All configuration values have defaults, a minimal configuration to get Laminar running is shown below. By default, the web interface is available on port 8080.

(service laminar-service-type)

Data Type: laminar-configuration

Data type representing the configuration of Laminar.

laminar (default: laminar): The Laminar package to use.
home-directory (default: "/var/lib/laminar"): The directory for job configurations and run directories.
bind-http (default: "*:8080"): The interface/port or unix socket on which laminard should listen for incoming connections to the web frontend.
bind-rpc (default: "unix-abstract:laminar"): The interface/port or unix socket on which laminard should listen for incoming commands such as build triggers.
title (default: "Laminar"): The page title to show in the web frontend.
keep-rundirs (default: 0): Set to an integer defining how many rundirs to keep per job. The lowest-numbered ones will be deleted. The default is 0, meaning all run dirs will be immediately deleted.
archive-url (default: #f): The web frontend served by laminard will use this URL to form links to artefacts archived jobs.
base-url (default: #f): Base URL to use for links to laminar itself.