| |
|
| |
It is not yet clear how notifications will work.
|
| |
|
| - |
## Components when integrating an external CI system
|
| - |
|
| - |
For external CI, the components are:
|
| - |
|
| - |
* the Radicle node
|
| - |
* the CI broker
|
| - |
* an adapter executable for each supported external CI instance
|
| - |
* the external CI instance
|
| - |
|
| - |
The first three of these run on the same host, but the external CI
|
| - |
instance can run anywhere. The adapter talks to the CI instance using
|
| - |
whatever protocol the CI instance supports, such as HTTP.
|
| - |
|
| - |
~~~dot
|
| - |
digraph "" {
|
| - |
radicle_node [label="Radicle node"];
|
| - |
broker [label="CI broker"];
|
| - |
adapter [label="Adapter"];
|
| - |
engine [label="External CI system"];
|
| - |
|
| - |
radicle_node -> broker [label="change event"];
|
| - |
broker -> adapter [label="invoke"];
|
| - |
adapter -> engine [label="run"];
|
| - |
engine -> adapter [label="web hook?"];
|
| - |
adapter -> broker [label="result"];
|
| - |
}
|
| + |
## Components of Radicle CI
|
| + |
|
| + |
Using CI with Radicle requires several co-operating components:
|
| + |
|
| + |
* The Radicle node (`radicle-node`).
|
| + |
* The Radicle CI broker (`cib`).
|
| + |
* An adapter the runs CI, possibly using an external CI service.
|
| + |
* A management tool (`cibool`).
|
| + |
|
| + |
~~~pikchr
|
| + |
right
|
| + |
Node: ellipse "radicle-node" fill Beige
|
| + |
move
|
| + |
move
|
| + |
Cib: ellipse "cib" fill Azure
|
| + |
down
|
| + |
move
|
| + |
Adapter: box "adapter" fill Azure
|
| + |
move
|
| + |
External: box "external" "CI" "system" fill Aquamarine
|
| + |
|
| + |
move right from Cib.e then then right then right then up
|
| + |
Db: cylinder "SQLite" "db" fill Pink
|
| + |
|
| + |
move up Cib.height from Cib.n
|
| + |
Cibtool: ellipse "cibtool" fill Azure
|
| + |
arrow thin from Cibtool.e to Db.nw <->
|
| + |
|
| + |
move from Db.s down 150%
|
| + |
Logs: cylinder height 200% "CI run" "logs" "reports" fill Pink
|
| + |
|
| + |
arrow thin from Node.e to Cib.w "node" above "event" below
|
| + |
arrow thin from Cib.ne to Db.sw <->
|
| + |
arrow dotted from Cib.e to Logs.nw
|
| + |
arrow dotted from Adapter.e to Logs.sw
|
| + |
|
| + |
Req: arc thin dashed from Cib.sw to Adapter.nw ->
|
| + |
move left 15% from Req.c
|
| + |
text "stdin" small "trigger" small
|
| + |
|
| + |
Resp: arc thin dashed from Adapter.ne to Cib.se ->
|
| + |
move right 15% from Resp.c
|
| + |
text "stdout" small "result" small
|
| + |
|
| + |
arrow thin dashed from External.n to Adapter.s <->
|
| |
~~~
|
| |
|
| - |
External CI integration works like this:
|
| - |
|
| - |
* a repository known to the node changes
|
| - |
- a Git ref is updated
|
| - |
- the ref can be a branch, tag, or something else, such as a Radicle
|
| - |
COB
|
| - |
- the node emits an event describing the change
|
| - |
* the CI broker listens to node events
|
| - |
- the broker subscribes to node events via the node control socket,
|
| - |
which is a Unix domain socket
|
| - |
* the CI broker filters events, based on its configuration, and the
|
| - |
configuration for the repository involved
|
| - |
* for an event that passes its filters, the CI broker spawns the
|
| - |
appropriate adapter process
|
| - |
- there is a different adapter for each different CI implementation
|
| - |
* the broker sends a request object to the adapter as a child process,
|
| - |
via the child's stdin, and reads any responses from the child's
|
| - |
stdout
|
| - |
- the request is JSON
|
| - |
- the responses are in the form of JSON Lines: a JSON object per
|
| - |
line serialized to not contain newline characters
|
| - |
* the adapter communicates with the external CI instance in whatever
|
| - |
way is suitable for that instance
|
| - |
- this is usually over HTTP
|
| - |
- it may involve the CI instance making a web hook request back to
|
| - |
the adapter
|
| + |
The node emits an event (`RefsFetched`), when it has fetched updates
|
| + |
to one of the repositories it has. The event specifies the repository,
|
| + |
and every Git ref. The CI broker parses this event to extract
|
| + |
information about the kind of change: branch has created? updated?
|
| + |
deleted? Likewise for tags and patches, etc. These become "CI events",
|
| + |
to distinguish them from "node events".
|
| + |
|
| + |
The node operator can specify filters on CI events, and if an event
|
| + |
gets past a filter, the CI broker will run an external program called
|
| + |
an "adapter". The adapter has the responsibility of running CI for the
|
| + |
change, and to report to the CI broker if it succeeded or failed.
|
| + |
|
| + |
Communication with the adapter is via the adapter's standard input
|
| + |
and output, using single-line JSON messages.
|
| |
|
| |
~~~plantuml
|
| |
@startuml
|
| - |
node -> broker : RefsFetched event
|
| - |
broker -> adapter : spawn
|
| - |
broker -> adapter : send request
|
| + |
node -> cib : RefsFetched event
|
| + |
cib -> adapter : spawn
|
| + |
cib -> adapter : send request
|
| |
adapter-> engine : trigger run
|
| - |
engine -> worker : start run
|
| - |
note over worker : perform the run
|
| |
engine -> adapter : response with run id
|
| - |
adapter -> broker : response: run id
|
| - |
worker -> engine : run finished
|
| - |
engine -> adapter : web hook?
|
| - |
adapter -> broker : response: result
|
| + |
adapter -> cib : response: run id
|
| + |
engine -> adapter : result of run
|
| + |
adapter -> cib : response: result
|
| |
@enduml
|
| |
~~~
|
| |
|
| - |
## Components in native CI
|
| - |
|
| - |
CI support in Radicle consists of several components. For native CI
|
| - |
they are:
|
| - |
|
| - |
* the Radicle node
|
| - |
* the CI broker
|
| - |
* the native CI executable
|
| - |
|
| - |
These all run on the same host.
|
| - |
|
| - |
~~~dot
|
| - |
digraph "" {
|
| - |
radicle_node [label="Radicle node"];
|
| - |
broker [label="CI broker"];
|
| - |
native [label="Native CI"];
|
| - |
commands [label="Shell commands \n from .radicle/native.yaml"];
|
| - |
|
| - |
radicle_node -> broker [label="change event"];
|
| - |
broker -> native [label="invoke"];
|
| - |
native -> commands [label="run"];
|
| - |
native -> broker [label="result"];
|
| - |
}
|
| - |
~~~
|
| - |
|
| - |
~~~plantuml
|
| - |
@startuml
|
| - |
node -> broker : RefsFetched event
|
| - |
broker -> adapter : spawn
|
| - |
broker -> adapter : send request
|
| - |
adapter -> broker : response: run id
|
| - |
note over adapter : perform the run
|
| - |
adapter -> broker : response: result
|
| - |
@enduml
|
| - |
~~~
|
| |
|
| + |
The CI broker also generates HTML report pages to list all the CI runs
|
| + |
it has performed.
|
| |
|
| |
# The adapter
|
| |
|