# Radicle CI Integration Options

This doc is a quick summary of the different integration possibilities between the Radicle Node and an external CI server.

## Scope

* in scope:
* how the Radicle Code Collab solution can integrate with existing CI systems
* out of scope:
* any discussion around how a new Decentralized CI solution might look like in terms of how it would orchestrate its CI workload in a p2p setting, etc. etc.

## End goal: Full Integration

This section starts by describing what the end integration looks like. Skip ahead to [Step 1](#Step-1-External-to-radicle-integration) if you want to take a step-by-step approach instead and come back to this section in the end.

1. Radicle Node emits necessary events for CI integration (e.g. "push", "patch", "patch comment", etc.)
2. Some listener (whether internal to the radicle node process or not) reacts to **relevant** events, in order to:
1. read the CI pipeline definition from the radicle project (usually a .yaml file in git)
2. create a CI pipeline in the CI server
3. read some project-specific configuration about which events the maintainers of this project want to trigger jobs
4. decide whether to trigger a pipeline run or not
3. The pipeline runs in the CI server (more accurately - some agent / worker node that is connected to the CI server)
4. The relevant **commit** needs to be updated with some "CI Check data"
- "Commit" and not "Patch", because CI jobs can also run post-patch merge
- This potentially sounds like a new Collaborative Object (Cob) (?)
- The process writing this Cob needs to have radicle tooling:
- an identity, that other radicle peers can track, in order to see the cob updates
- some cli command that allows it to update the cob
- a radicle node for itself (if this functionality is not implemented inside radicle node itself), so that it can communicate this change to the p2p network.
- The process writing this Cob needs to tightly integrate with the CI server:
- poll CI server for pipeline run results
- accept push events (e.g. webhook) when job is finished (with some backup mechanism to refresh results, in case push event is lost)
5. Radicle interface, terminal UI (and all other clients) need to be taught to display the above information
- this is the equivalent of the "Checks" tab in GitHub PRs, or the "Pipelines" tab in GitLab, etc. etc. and also the passing/failing job status icon when the git log is displayed.
- these tools will eventually need to learn how to act based on this information (e.g. prevent a Patch being merged, in case the delegates have laid out such a policy in the "radicle project settings" (this implies some extension to the model))
- the radicle interface in particular (but perhaps also other clients) will also need to learn how to write these relevant "radicle project settings", so delegates can lay out their own patch merging rules (e.g. don't merge when CI is broken).
- delegates can always overwrite any information and proceed with merging, so this is more of a "reminder" / guardrail

## Step 1: External-to-radicle integration
* external to radicle process:
1. monitors node events and
2. triggers preconfigured CI jobs
* no updates are made to radicle patches
* developers have to manually check CI server to figure out if jobs passed or not

### Benefits

* Lowest effort, shortest path to triggering some CI job in an automated way

### Limitations

* still pretty poor developer experience overall - manually checking job results

## Step 2: Pipeline Events and Results as comment in Patch

* this builds on step 1 by offering a somewhat improved user experience as the developers no longer have to poll the CI server to see job results
* when pipeline starts, a comment is added to the patch proposal, with a URL to the CI server job
* when pipeline finishes, another comment is added to the patch proposal, with the pipeline status (passing / failed) - and, optionally, the error message, in case of failure.

### Benefits

* comments are already supported, so we can worry about all the "Check" model and `Cob` details later.
* having a way to add comments already solves a part of the bigger problem: how can we make changes to the radicle project (in this case, adding a comment) based on CI job results and publish those changes to the network.

### Limitations

* we cannot yet use pipeline status to decide whether patches can be merged or not (since there are no "checks" yet to decide over)

## Step 3: Build "Checks" model into Radicle

* this would build on step 2, gradually replacing the comments that the CI job would add
* instead of comments:
* we would design a first version of the "Checks" Cob
* write "Checks" cobs instead of comments
* visualize "Checks" in our respective UIs (web, TUI, IDEs)

Note: "Checks" is a placeholder name till we come up with something better. Please feel free to leave an inline comment with your suggestion

## Step "X"

* Yes, there is additional functionality that can be included. This section is left for future work in this area. If you think some area that should have a higher priority than those laid out above, please suggest it here. ; )