Concourse.nix

Nix module and overlay for Concourse CI.

Installation

This flake provides 3 outputs:

1. .overlays.default: An overlay for pkgs.concourse and pkgs.fly
2. .module.web: The web service module
3. .module.worker: The worker service module

Configuration

For an example, see service integration test. Enable concourse by adding the provided modules in a nixosConfigurations

# Flake
{
  inputs = {
    ...
    concourse = {
      url = "git+https://codeberg.org/aniva/Concourse.nix.git";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}
...

module-overlay = {
  nixpkgs.overlays = [(import package/overlay.nix) inputs.concourse.overlays.default];
};

# nixosConfigurations
imports = [
	inputs.concourse.module.web
	inputs.concourse.module.worker
	module-overlay
]

Then, enable concourse.web or concourse.worker services. The options listed here must be configured for Concourse to run pipelines.

services.concourse.web = {
  enable = true
  ...
  postgres = ...;
  auth = ...;
  network = ...;
  tsa = ...;
  sessionSigningKey = ...;
  environment = {};
}

Configuring the worker is similar

services.concourse.worker = {
  enable = true
  ...
  resourceTypes = with pkgs.concourse.resource-types; [
    registry-image
    git
    time
  ];
  tsa = ...;
  environment = {};
}

Authentication

A web node must declare a method of authentication. Configure authentication using the services.concourse.web.auth.{local,oidc} option or via environment variables.

Resource Types

Every Concourse worker node must advertise a list of resource types which it can deploy. The available resource types are listed in resource-types. In addition to the bundled resource types from Concourse, this flake incorporates 3rd party resource types for the ease of maintenance:

• rclone: File transfer using rclone (forked from warricksothr/concourse-rclone-resource)
• git-branches: Track Git branches (forked from aoldershaw/git-branches-resource)
• forgejo: Forgejo interactions using concourse-forgejo

The user can define custom resource types using pkgs.concourse.resource-types.make function, where

pkgs.concourse.resource-types.make {
  type,    # Name of the resource type
  version, # Version
  privileged ? false,
  unique_version_history ? false,
  image,  # A `buildImage` result of the resource
}

The files /opt/resources/{check,in} must be available in the image.

Contributing

All code must be formatted with nix fmt . before checking in. Use the provided development shell and .pre-commit-config.yaml using direnv:

echo "use flake" > .envrc
direnv allow
prek install

When upstream Concourse source receives an update, fetch the new version using

nix run .#update $version

Adopting and Testing Resources

We can adopt unmaintained resources into Concourse.nix and deploy them in lockstep with Concourse itself. This eliminates the difficulty of tracking many resource versions. Adopted resources should go into package/resource-types.

Resources should be tested using the machinery in test/common. This is especially applicable to resources adopted from outside. Refer to the test sin test/resource for examples.