CI is a declarative continuous integration and testing system built on top of Nix and the NixOS module system. Its aim is to be flexible in order to meet the many needs of the various technologies and cloud providers in use with CI today, while being simple and self-contained so that all actions can be performed on a local machine. Build results should be reproducible so if it works on your machine then it will work on the CI server as well!
Some of the project's goals and features are...
The same reproducibility guarantees provided by the Nix and NixOS ecosystem, offering consistent builds that will produce the same results whether they run on your laptop or in the cloud.
Matrix builds that run locally as well as on remote CI servers.
Integration with the Nix store to cache and avoid repeating unnecessary work.
Included escape hatches for tests, commands, and deployments that require the network or other resources that would normally be restricted by using Nix.
Integration with existing CI providers while being agnostic to the underlying service, allowing the same configuration to work with multiple providers while still providing dashboards and results that reflect your configuration.
Ability to publish results and perform follow-up actions and notifications without being constrained to any particular provider's capabilities.
(this is currently all very much WIP right now, but please do file issues if you actually use it and have questions or concerns!)
To start, it's covenient to have the ci channel available to nix on your
system:
$ export NIX_PATH=$NIX_PATH:ci=https://github.com/arcnmx/ci/archive/v0.6.tar.gz
This allows the channel to be easily referred to while testing locally, like so:
$ nix run -f '<ci>' help
$ nix run -f '<ci>' --arg config '<ci/examples/ci.nix>' test
✔️ hello, world ok
You can also manage it with nix-channel, though due to a nix limitation you
are still required to include the channel name in NIX_PATH in some way:
$ nix-channel --add https://github.com/arcnmx/ci/archive/v0.6.tar.gz ci
$ nix-channel --update
$ export NIX_PATH=$NIX_PATH:ci=/xxx
Global and CI commands can be found with the list command:
$ nix run -f '<ci>' list
list
run.gh-actions-generate
run.test.example
test
Commands under a job or stage sub-configuration can be accessed by name via
ci.job.jobName.run and ci.stage.name.run respectively.
Documentation is a bit sparse right now, but a few examples are currently available:
Appendix A, Configuration Options lists all the options available for customizing your CI process!
Appendix B, Environment Variables documents the environment variables provided by and used for
configuring the CI. It may be convenient to set some of these for a project in the relevant
shell.nix or .direnv files.