MiniCI

Simple minimalist framework to run CI-like checks on local machine, used by Erebos projects.

The code can be downloaded here:

git clone https://code.erebosprotocol.net/minici

from a mirror on github:

git clone https://github.com/roman-smrz/minici

or from Hackage:

https://hackage.haskell.org/package/minici

Installation

Debian

For installation and updates using apt, new repository can be added by creating a file named /etc/apt/sources.list.d/erebos.sources:

Types: deb
URIs: https://repo.erebosprotocol.net/debian/
Suites: DIST
Components: main
Signed-By: /etc/apt/keyrings/erebos.gpg

Where DIST needs to be changed to the distribution codename: bookworm or trixie.

Download and install the repository key:

# wget -O /etc/apt/keyrings/erebos.gpg https://repo.erebosprotocol.net/erebos.gpg

Update apt database and install minici:

# apt update
# apt install minici

Binary release

Prebuilt binary with minimal dependencies — apart from the git command, which needs to be installed for most of the functionality — is available for 64bit Linux:

//repo.erebosprotocol.net/download/minici/v0.1.6/

The archive there contains executable that can be run from any location:

$ tar xzf minici-0.1.6_linux_amd64.tar.gz
$ ./minici-0.1.6_linux_amd64/minici --version
MiniCI version 0.1.6

To build from source, use the cabal tool either within the source directory:

$ tar xzf minici-0.1.6.tar.gz
$ cd minici-0.1.6
$ cabal install

or to automatically download the source from Hackage:

$ cabal install minici

Readme

MiniCI runs jobs defined in the minici.yaml file in the root of the project (on the same level as the .git directory). With that, minici invocation can execute the jobs for local commits that are not yet in upstream (remote) branch or for any manually given commit range.

Job definition

The top-level elements of the YAML file are job <name> defining steps to perform the job and potentially listing artifacts produced or required.

Example:

job build:
  shell:
    - make
  artifact bin:
    path: build/example

job test:
  uses:
    - build.bin
  shell:
    - ./build/example test

Each job is a map with the following attributes:

shell: List of shell commands to perform the job
artifact <name> (optional): Defines artifact <name> produced by this job. Is itself defined as a dictionary.
artifact <name>.path: Path to the produced artifact file, relative to the root of the project.
uses (optional): List of artifact required for this job, in the form <job>.<artifact>.

Usage

To run jobs for a git commit range:

minici run <commit>..<commit>

or:

minici run --range=<commit>..<commit>

To run jobs for commits that are in local <branch>, but not yet in its upstream:

minici run --since-upstream=<branch>

For current branch, the name can be omitted:

minici run

To run selected jobs with the current working tree, including uncommitted changes, list the job names on command line:

minici run <job name> [<job name> ...]

To watch changes on given <branch> and run jobs for each new commit:

minici run --new-commits-on=<branch>

To watch new tags and run jobs for each tag matching given pattern:

minici run --new-tags=<pattern>

The above options --range, --since-upstream, etc can be arbitrarily combined.

Roadmap

0.1.7

Reflect dependencies in job id
Canonical job ids
Command to display logs for given job
Command to extract artifacts
Log-style output suitable for pipes or files
Run jobs by explicit id/ref

0.1.x

Run dependencies of jobs specified on command line
Cancel no longer relevant generated jobs (after not-fast-forward branch move)
Checkout from remote git repositories
Jobs to publish artifacts to specified destination
Support whole directories as artifacts

0.2.0

Secure container for running jobs
Switch to erebos storage
Follow logs of unfinished jobs in log command

Backlog

Reference and watch other repositories from minici.yaml to generate jobs
Include jobs from other minici.yaml files
HTTP server providing web interface

Changelog

0.1.6 – 2025-03-30

Added jobid command resolving job reference to canonical ID
Fix copying of used artifacts to appropriate working directory

0.1.5 – 2025-03-20

Accept job file path on command line
Added checkout command
Reference and checkout other repositories from job file
Accept names of jobs to run as command-line arguments

0.1.4 – 2025-02-04

Fix invocation of minici run without arguments
Fix that empty temporary dir was not deleted in some cases
Add explicit --since-upstream option for the run command

0.1.3 – 2025-01-25

Run jobs based on configuration in associated commit
Configurable number of concurrently running jobs (using -j option)
Concurrently run jobs for multiple commits
Properly cancel and clean up jobs on user interrupt
Added --new-commits-on and --new-tags options for run command to dynamically generate jobs based on branch/tags changes
Support for GHC up to 9.12

0.1.2 – 2024-07-30

Explicit run command
Support for GHC up to 9.10

0.1.1 – 2023-04-25

Support for GHC 9.2
Added -V command-line switch to show version.

0.1.0 – 2023-02-04

First version.