radicle-ci-broker

Add integration to CI engines/systems/services to Radicle, a distributed git hosting and collaboration system. See Radicle CI for an overview.

Documentation

The doc directory holds some documentation for the Radicle CI Broker:

• If you plan to user radicle-ci-broker, checkout the User guide
• If you plan to contribute or extend radicle-ci-broker, checkout the architecture document

HTML pages can be generated from the documentation. To build those, run make in the doc directory:

RADICLE_CI_BROKER_WEBROOT=/tmp/ci make -C doc publish

The RADICLE_CI_BROKER_WEBROOT environment variable defines where the generated HTML pages should end up.

You'll need some tools installed: Pandoc, graphviz (dot), PlantUML, pikchr-cli. The latter is a Rust crate, so you can install it with cargo install pikchr-cli. The other dependencies can usually be installed through your system package manager. Note there's a flake.nix that provides all the needed tools, use it with the usual nix develop command.

Binaries

The crate contains several binaries:

• cib --- the actual CI broker
  • this is the only one you need to care about, the rest are for debugging
• cibtool --- management tool for node operators, for managing the CI broker
• synthetic-events --- test tool for CI broker developers

Packaging

There is simple, simplistic, rudimentary, personal-use-only packaging for Debian in the debian directory, used by Lars to build packages for his own use.

Running from the source tree

To run cib or cibtool from the source tree:

cargo run --bin cib -- --config config.yaml process-events
cargo run --bin cibtool -- --db ci-broker.db event list

Note the -- argument. It tells cargo run that all the arguments that follow are to be passed to the program being run, and not used by cargo itself.

Running tests

To run the test suite for the CI broker:

cargo test

(The usual way, for a Rust program.)

In addition to the usual Unix command line tools, you need the following programs installed for the test suite:

• jq
• git
• sqlite3
• rad (from Radicle)
• git-remote-rad (from Radicle)
• subplot (Instructions here. Required for doc make target.)

Configuration

The configuration file is named on the command line. It is a YAML file. See ci-broker.md for examples. Those examples are verified to work every time the test suite runs.

Adapters

You need to use an "adapter" together with the CI broker to actually run CI on projects. At least the following adapters for external CI systems are known:

• Radicle Ambient adapter
  • Run CI using Ambient CI, in an isolated VM, for safety and security.
• Radicle native CI
  • Run CI on the node directly, using .radicle/native.yaml
• Concourse integration
  • Integrate with the Concourse CI system
• GitHub actions
  • Integrate with GitHub actions
• Outgoing web hooks
  • Call a remote web hook when an event occurs in a repository hosted on the Radicle network
• Kraken
  • Integrate with the Kraken CI system
• Zulip Integration
  • Integrate with Zulip chat for getting informed about new events on repos
• Container CI
  • Run CI on the node in podman containers, using .radicle/native.yaml (Radicle Native CI compatibility) or .radicle/cci.yaml

See also the radicle-ci-integrations-docs repository with guides for project maintainers and node operators about using Radicle CI. They too list CI adapters.

License

Radicle CI broker is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.