mirror of
https://seed.radicle.dev/rad:zwTxygwuz5LDGBq255RA2CbNGrz8.git
synced 2026-11-03 19:00:28 +08:00
Lars Wirzenius
64def56ddf
Also drop PATH from the `cib` config example in the user guide, as it's not always necessary.
121 lines
4.5 KiB
Markdown
121 lines
4.5 KiB
Markdown
# radicle-ci-broker
|
|
|
|
Add integration to CI engines/systems/services to
|
|
[Radicle](https://radicle.dev/), a distributed git hosting and
|
|
collaboration system. See [Radicle CI](https://radicle-ci.liw.fi/)
|
|
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](doc/userguide.md)
|
|
* If you plan to contribute or extend `radicle-ci-broker`, checkout the [architecture document](doc/architecture.md)
|
|
|
|
HTML pages can be generated from the documentation. To build those,
|
|
run `make` in the `doc` directory.
|
|
|
|
~~~
|
|
make -C doc
|
|
~~~
|
|
|
|
You'll need some tools installed: [Pandoc](https://pandoc.org),
|
|
[graphviz](https://www.graphviz.org) (dot),
|
|
[PlantUML](https://plantuml.com),
|
|
[pikchr-cli](https://crates.io/crates/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](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:
|
|
|
|
~~~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)
|
|
* `subplot` (Instructions [here](https://subplot.tech/download/). Required for `doc` make target.)
|
|
|
|
## Configuration
|
|
|
|
The configuration file is named on the command line. It is a YAML
|
|
file. See [`ci-broker.md`](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](https://radicle.network/nodes/radicle.liw.fi/rad:z35CgFVYCKpqqDtJMzk8dyE6dViS6)
|
|
- Run CI using Ambient CI, in an isolated VM, for safety and security.
|
|
* [Radicle native CI](https://radicle.network/nodes/seed.radicle.dev/rad:z3qg5TKmN83afz2fj9z3fQjU8vaYE)
|
|
- Run CI on the node directly, using `.radicle/native.yaml`
|
|
* [Concourse integration](https://radicle.network/nodes/index.radicle.garden/rad:z3G4JeCL1UaS7TwoQHgY2VidbX2Ai/tree/concourse-adapter/README.md#documentation)
|
|
- Integrate with the Concourse CI system
|
|
* [GitHub actions](https://radicle.network/nodes/index.radicle.garden/rad:z3G4JeCL1UaS7TwoQHgY2VidbX2Ai/tree/github-actions-adapter/docs/project_setup.md)
|
|
- Integrate with GitHub actions
|
|
* [Outgoing web hooks](https://radicle.network/nodes/index.radicle.garden/rad:z3G4JeCL1UaS7TwoQHgY2VidbX2Ai/tree/webhooks-adapter/docs/webhook_settings_persistence.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://radicle.network/nodes/index.radicle.garden/rad:z3G4JeCL1UaS7TwoQHgY2VidbX2Ai/tree/zulip-adapter/README.md)
|
|
- Integrate with Zulip chat for getting informed about new events on repos
|
|
* [Container CI](https://radicle.network/nodes/rad.levitte.org/rad:z2ZTDBgsGxMDyLjATZ4rcr63twmTJ)
|
|
- Run CI on the node in `podman` containers, using `.radicle/native.yaml` (Radicle Native CI compatibility) or `.radicle/cci.yaml`
|
|
* [Tekton](https://radicle.network/nodes/seed.siryu.me/rad%3Azg2VS9DsGqxqLCWJ8Km3ztrd3ba1)
|
|
- Run CI on Tekton using `.radicle/tekton.yaml`
|
|
|
|
## 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.
|