|
|
|
@@ -0,0 +1,200 @@
|
|
|
|
|
---
|
|
|
|
|
title: Radicle native CI
|
|
|
|
|
subtitle: Requirements and architecture
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
# Introduction
|
|
|
|
|
|
|
|
|
|
This document explains the purpose of the Radicle native CI component,
|
|
|
|
|
the requirements put on it, and its software architecture.
|
|
|
|
|
|
|
|
|
|
# Overview
|
|
|
|
|
|
|
|
|
|
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 have to run on the same host: the node and broker
|
|
|
|
|
communicate via a Unix domain socket, and the broker spawns the native
|
|
|
|
|
CI executable.
|
|
|
|
|
|
|
|
|
|
See the CI broker architecture documentation for a more in-depth
|
|
|
|
|
description of CI in Radicle.
|
|
|
|
|
|
|
|
|
|
The child process is called "the CI adapter" in this document.
|
|
|
|
|
|
|
|
|
|
Native CI works like this:
|
|
|
|
|
|
|
|
|
|
* reads a request message from its standard input
|
|
|
|
|
* clones the git repository in the request
|
|
|
|
|
* switches to the commit in the request
|
|
|
|
|
* reads the `.radicle/native.yaml` file in the repository
|
|
|
|
|
* writes a response message saying it starts a run, to its standard
|
|
|
|
|
output
|
|
|
|
|
* executes the shell snippet in the `.native.yaml` file
|
|
|
|
|
* writes a response message with the result of the run
|
|
|
|
|
* writes a log file based on what it did
|
|
|
|
|
* updates the `index.html` page that lists all CI runs and their
|
|
|
|
|
results
|
|
|
|
|
|
|
|
|
|
## Native CI
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The diagram above shows the happy path. Various things can go wrong,
|
|
|
|
|
after the native CI executable has started. (In this document we don't
|
|
|
|
|
need to consider other possible failures.) The test suite for native
|
|
|
|
|
CI verifies that they're all handled correctly, either by explicitly
|
|
|
|
|
testing each case, or relying on analysis that generic error handling
|
|
|
|
|
copes with the case. See the `test-suite` program in the source tree.
|
|
|
|
|
|
|
|
|
|
* the environment variable specifying the configuration file is not
|
|
|
|
|
set
|
|
|
|
|
* can't read or parse the configuration file
|
|
|
|
|
* the configuration file does not specify all mandatory fields
|
|
|
|
|
* the configuration file specifies values that are wrong in some way
|
|
|
|
|
* stdin is empty
|
|
|
|
|
* stdin does not contain a newline
|
|
|
|
|
* the first line of stdin can't be parsed as a message serialized as
|
|
|
|
|
JSON
|
|
|
|
|
* the message is not a trigger message
|
|
|
|
|
* the repository triggered does not exist
|
|
|
|
|
* the repository can't be cloned
|
|
|
|
|
* the repository does not have the requested commit
|
|
|
|
|
* the repository does not contain `.radicle/native.yaml`
|
|
|
|
|
* `native.yaml` can't be read or parsed as YAML
|
|
|
|
|
* `native.yaml` does not contain a text field `shell`
|
|
|
|
|
* writing first response to stdout fails
|
|
|
|
|
* there is any problem executing the contents of the `shell` field
|
|
|
|
|
using `bash`
|
|
|
|
|
* executing the shell snippet takes too long
|
|
|
|
|
* generating or writing a "run metadata" file fails
|
|
|
|
|
* writing second response to stdout fails
|
|
|
|
|
* finding or parsing all run metadata files fails
|
|
|
|
|
* generating or writing the static web pages listing all runs fails
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# Requirements
|
|
|
|
|
|
|
|
|
|
Overall, the native CI engine, or adapter, is very simple. However, it
|
|
|
|
|
must be robust, which makes things more difficult. Here, robust means
|
|
|
|
|
that whatever happens, the node owner finds out what it was. If a run
|
|
|
|
|
fails for whatever reason, the node owner can figure out why. Ideally,
|
|
|
|
|
this applies to anyone watching CI on the node can see it as well.
|
|
|
|
|
|
|
|
|
|
In the descriptions of the requirements we use the following roles:
|
|
|
|
|
|
|
|
|
|
* "developer" makes changes to the repository on which CI is run
|
|
|
|
|
* "node owner" runs the node itself
|
|
|
|
|
|
|
|
|
|
The native CI engine has several ways to report what it does:
|
|
|
|
|
|
|
|
|
|
* its standard error output
|
|
|
|
|
- in a systemd setup this is captured to the system log or journal
|
|
|
|
|
* a per-node log file for native CI
|
|
|
|
|
- this is for this that interest only the node owner, not the
|
|
|
|
|
developer
|
|
|
|
|
- e.g., finding configuration errors that the developer can't fix,
|
|
|
|
|
such a missing configuration file
|
|
|
|
|
* a per-run log file
|
|
|
|
|
- this of interest to both the node owner and the developer
|
|
|
|
|
- this is the primary tool for the developer to figure out what went
|
|
|
|
|
wrong in their CI run, so that they can change their repository to
|
|
|
|
|
fix it
|
|
|
|
|
|
|
|
|
|
## Developer can see what status of each CI run on a node
|
|
|
|
|
|
|
|
|
|
_Requirement:_ The developer can see what CI runs a node has
|
|
|
|
|
triggered, and what the current status of each is.
|
|
|
|
|
|
|
|
|
|
_Justification:_ This lets them be reassured that CI is working.
|
|
|
|
|
|
|
|
|
|
_Implementation:_ Native CI maintains one or more web pages that list
|
|
|
|
|
every run. For each run, the following is recorded:
|
|
|
|
|
|
|
|
|
|
## Developer gets a useful run log
|
|
|
|
|
|
|
|
|
|
_Requirement:_ The developer can fetch a useful log of a run that
|
|
|
|
|
helps them find out problems in their code.
|
|
|
|
|
|
|
|
|
|
_Justification:_ This is crucial for the developer to have any hope of
|
|
|
|
|
fixing a problem found in CI.
|
|
|
|
|
|
|
|
|
|
_Implementation:_ The run log is a static file that can be fetched via
|
|
|
|
|
HTTP from the node, or viewed in a web browser. The run log contains
|
|
|
|
|
at least the following information:
|
|
|
|
|
|
|
|
|
|
* the repository ID
|
|
|
|
|
* the repository alias, if one is known to the local node
|
|
|
|
|
* the commit id that triggered the run
|
|
|
|
|
* the commit diff (`git show`)
|
|
|
|
|
* when the run was triggered
|
|
|
|
|
* when the run finished
|
|
|
|
|
* the environment variables of the native CI process
|
|
|
|
|
* every command or other action that was taken during the run
|
|
|
|
|
* the standard output and standard error output, and the exit code, of
|
|
|
|
|
every command
|
|
|
|
|
* whether the run was considered successful or not
|
|
|
|
|
|
|
|
|
|
## Node owner is informed via system log if CI fails early
|
|
|
|
|
|
|
|
|
|
_Requirement:_ If a native CI run fails early, it writes a message to
|
|
|
|
|
its standard error output.
|
|
|
|
|
|
|
|
|
|
_Justification:_ The standard error is captured by systemd, and
|
|
|
|
|
written to the system log or journal, from where the node owner can be
|
|
|
|
|
expected to find it. This gives them a chance to find out what's wrong
|
|
|
|
|
and hopefully fix it.
|
|
|
|
|
|
|
|
|
|
"Early" here means any time before the broker has been given a
|
|
|
|
|
"result" response message, and a per-run log file has been created,
|
|
|
|
|
and the web page of all CI runs has been updated.
|
|
|
|
|
|
|
|
|
|
_Implementation:_ Use a suitable Rust logging library, with the
|
|
|
|
|
default log level allowing only error messages, and only logging an
|
|
|
|
|
error if something goes wrong early.
|
|
|
|
|
|
|
|
|
|
## Only early failures are logged to the system log
|
|
|
|
|
|
|
|
|
|
_Requirement:_ The native CI engine only writes to its standard error
|
|
|
|
|
output when it fails early. Otherwise it only updates its per-run and
|
|
|
|
|
per-node log files.
|
|
|
|
|
|
|
|
|
|
_Justification:_ It's easy to spam the system log with many useless
|
|
|
|
|
messages, which make it harder to find important information in the
|
|
|
|
|
log.
|
|
|
|
|
|
|
|
|
|
## The per-node log is updated when an early error occurs
|
|
|
|
|
|
|
|
|
|
_Requirement:_ If native CI writes an error message to the standard
|
|
|
|
|
error output, it is also written to the per-node log, with more
|
|
|
|
|
detail.
|
|
|
|
|
|
|
|
|
|
_Justification:_ The system log is a bad place to report detailed
|
|
|
|
|
information, as it's quite constrained. A per-node log provides more
|
|
|
|
|
flexibility.
|
|
|
|
|
|
|
|
|
|
_Implementation:_ Append to a per-node log, and if that fails, report
|
|
|
|
|
that, too, to the standard error output.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# Test architecture
|
|
|
|
|
|
|
|
|
|
In order to test the native CI engine, we invoke it in various ways,
|
|
|
|
|
and examine its outputs.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
In order for the native CI engine to work, it needs to clone from a
|
|
|
|
|
node. This is awkward for testing. Using a real node is possible, but
|
|
|
|
|
introduces more moving parts that can fail during tests. Using a test
|
|
|
|
|
double, or mock, as the node would be possible, but more work, and
|
|
|
|
|
it'd be somewhat tricky logic, which is likely to introduce bugs.
|
|
|
|
|
|
|
|
|
|
We implement the test suite to use a specially set up local node, with
|
|
|
|
|
a repository with contents for tests. We will create the node as part
|
|
|
|
|
of the test suite so that it has exactly the content we need for the
|
|
|
|
|
tests.
|
Lars Wirzenius