mirror of
https://seed.radicle.dev/rad:zwTxygwuz5LDGBq255RA2CbNGrz8.git
synced 2026-11-16 00:30:35 +08:00
Fintan Halpenny
8cbc1fe313
While setting up a Nix flake, a series of tests were failing due to shell invocations. The falling were the changes required: - Use `!#/bin/sh` instead of `!#/bin/bash` - Use `$$` instead of `$BASHPID` - Use `true` and `false` instead of `/bin/true` and `/bin/false` It was also noted that the `git-remote-helper` is needed alongside the `rad` binary for some of the acceptance tests to work.
168 lines
5.0 KiB
Markdown
168 lines
5.0 KiB
Markdown
# radicle-ci-broker
|
|
|
|
Add integration to CI engines/systems/services to
|
|
[Radicle](https://radicle.xyz/), a distributed git hosting and
|
|
collaboration system.
|
|
|
|
This is not quite production ready code yet, but it will eventually become a
|
|
thing that listens for changes in a Radicle node, and triggers CI on
|
|
the relevant ones.
|
|
|
|
|
|
## Architecture
|
|
|
|
See the `doc` directory for architecture documentation. Quick summary:
|
|
the CI broker gets events from the Radicle node, filters them based on
|
|
its own config, and for any event that gets past the filter, runs the
|
|
configured adapter executable. The broker and adapter use a simple
|
|
JSON based message protocol over stdin/stdout. Each CI system has its
|
|
own adapter.
|
|
|
|
To build the documentation, run `make` in the `doc` directory. You'll
|
|
need some tools installed: Pandoc, graphviz (dot), PlantUML,
|
|
pikchr-cli. The others are widely packaged, pikchr-cli is a Rust
|
|
crate, so you can install it with `cargo install pikchr-cli`
|
|
|
|
Build and publish the documentation like this:
|
|
|
|
~~~
|
|
RADICLE_CI_BROKER_WEBROOT=/tmp/ci make -C doc publish
|
|
~~~
|
|
|
|
|
|
## 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:
|
|
|
|
~~~sh
|
|
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:
|
|
|
|
~~~sh
|
|
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)
|
|
|
|
## Configuration
|
|
|
|
The configuration file is named on the command line. It is a YAML
|
|
file, for example:
|
|
|
|
~~~yaml
|
|
default_adapter: native
|
|
db: ci-broker.sqlite
|
|
adapters:
|
|
native:
|
|
command: radicle-native-ci
|
|
env:
|
|
RADICLE_NATIVE_CI: /home/liw/radicle/radicle-native-ci/x/config.yaml
|
|
sensitive_env:
|
|
some_secret: some_secret_value_that_is_not_logged
|
|
filters:
|
|
- !And
|
|
- !Repository "rad:z2e6URdt1we1iG1BCVqtx8QVgsX4a"
|
|
- !Or
|
|
- !Branch "main"
|
|
- !AnyPatchRef
|
|
~~~
|
|
|
|
Or if you only want to filter for patch COB updates (e.g. comments),
|
|
to the specified repository:
|
|
|
|
~~~yaml
|
|
default_adapter: native
|
|
db: ci-broker.sqlite
|
|
adapters:
|
|
native:
|
|
command: radicle-native-ci
|
|
env:
|
|
RADICLE_NATIVE_CI: /home/liw/radicle/radicle-native-ci/x/config.yaml
|
|
sensitive_env:
|
|
some_secret: some_secret_value_that_is_not_logged
|
|
filters:
|
|
- !And
|
|
- !Repository "rad:z2e6URdt1we1iG1BCVqtx8QVgsX4a"
|
|
- !And
|
|
- !AnyPatch
|
|
- !Not
|
|
- !AnyPatchRef
|
|
~~~
|
|
|
|
This runs the native CI engine as an adapter, on any repository events
|
|
that pass the filter. The filter allows any changes to the `main`
|
|
branch or any Radicle patch, on the specified repository.
|
|
|
|
|
|
## 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 native
|
|
CI](https://app.radicle.xyz/nodes/seed.radicle.xyz/rad:z3qg5TKmN83afz2fj9z3fQjU8vaYE)
|
|
- Run CI on the node directly, using `.radicle/native.yaml`
|
|
* [Concourse integration](https://app.radicle.xyz/nodes/seed.radicle.garden/rad:z2woyw9Get9Q21VJzdbVz33b47xDb)
|
|
- Integrate with the Concourse CI system
|
|
* [GitHub actions](https://explorer.radicle.gr/nodes/seed.radicle.gr/rad:z4Uh671FzoooaHjLvmtW9BtGMF9qm/tree/Node-Operator/GitHub-Actions-Integration.md)
|
|
- Integrate with GitHub actions
|
|
* [Outgoing web hooks](https://explorer.radicle.gr/nodes/seed.radicle.gr/rad:z4Uh671FzoooaHjLvmtW9BtGMF9qm/tree/Node-Operator/Webhooks-Integration.md)
|
|
- Call a remote web hook when an event occurs in a repository hosted
|
|
on the Radicle network
|
|
* [Kraken](https://kraken.ci/blog/integration-with-radicle/)
|
|
- Integrate with the Kraken CI system
|
|
* [Zulip Integration](https://explorer.radicle.gr/nodes/seed.radicle.gr/rad:z4Uh671FzoooaHjLvmtW9BtGMF9qm/tree/Node-Operator/Zulip-Integration.md)
|
|
- Integrate with Zulip chat for getting informed about new events on repos
|
|
|
|
See also the
|
|
[radicle-ci-integrations-docs](https://explorer.radicle.gr/nodes/seed.radicle.gr/rad:z4Uh671FzoooaHjLvmtW9BtGMF9qm)
|
|
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](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details.
|