Radish alpha
r
radicle-ci-broker
rad:zwTxygwuz5LDGBq255RA2CbNGrz8
Radicle CI broker
Radicle
Git
Patches › 084803db
docs(doc/userguide.md): document "triggers" feature
Merged liw opened 1 year ago

Signed-off-by: Lars Wirzenius liw@liw.fi

Activity Changes +98 -0
1 file changed +98 -0 1336037b → 25a8d24d
modified doc/userguide.md
@@ -34,6 +34,15 @@ events", which are more suitable for the kind CI use that the CI
broker is meant to enable, than "this ref changed", which is quite low

level.
+ 
The CI events are filtered, and events that are allowed by the filter
+ 
trigger a CI run, which runs another program called the CI adapter.
+ 
The adapter arranges for a CI system or CI engine to execute CI for
+ 
the code change captured in the CI event. There are adapters for
+ 
different CI systems, such as GitHub Actions, Concourse, Kraken, and
+ 
also the "native adapter", that runs a shell script locally on the
+ 
host where the adapter runs. Each adapter may require a different
+ 
configuration to suit the CI system it targets.
+ 


# CI events



The CI broker currently supports a small set of CI events. There will
@@ -147,3 +156,92 @@ The conditions are expressed using the `!Foo` syntax in YAML. `Foo`
must be one of the operands from the table above. Simple values are

expressed as doubly quoted strings, and lists of operands are

sub-lists in YAML syntax.
+
+ 
The `filters` field is a list of filter expressions that implicitly
+ 
joined together using '!Or` -- in other words, if any of the
+ 
expressions in the list allows the event, the whole list allows the
+ 
events.
+
+ 
# Triggering CI
+
+ 
The Radicle CI broker can be configured to trigger CI runs in two
+ 
ways:
+
+ 
* a global filter and a default adapter
+ 
* a list of triggers, each of which has its own filter, and specifies
+ 
  an adapter to use
+
+ 
Example:
+
+ 
~~~yaml
+ 
adapters:
+ 
  foo:
+ 
    command: foo-adapter
+ 
    env:
+ 
      RADICLE_CI_FOO: foo-ci.yaml
+ 
  bar:
+ 
    command: bar-adapter
+ 
    env:
+ 
      RADICLE_CI_BAR: bar-ci.yaml
+ 
default_adapter: foo
+ 
filters:
+ 
  - !Branch "main"
+ 
triggers:
+ 
  - adapter: foo
+ 
    filters:
+ 
      - !Branch "staging"
+ 
  - adapter: bar
+ 
    filters:
+ 
      - !PatchCreated
+ 
      - !PatchUpdated
+ 
~~~
+
+ 
The above configuration specifies two aapters, `foo` and `bar`.
+
+ 
* `foo` is used for the `main` branch and `staging` branch
+ 
* `bar` is used for patches
+
+ 
Thus, if the `main` branch changes, the `foo` adapter is run. If a
+ 
branch other than `main` or `staging` changes, CI is not run.
+
+ 
## Configuring adapters
+
+ 
The `adapters` field in the configuration file gives a name to each
+ 
adapter. The name only matters within the configuration file, it has
+ 
no other significance, but each name must be different. For each
+ 
adapter the following fields are specified:
+
+ 
* `command` - the command by which the adapter is invoked
+ 
  - this is only the name of the command, without any options
+ 
  - the executable is found via the `PATH`, or the name can be an
+ 
    absolute path
+ 
* `env` is a mapping of name/value pairs; when the command is
+ 
  invoked, it is given each name as an environment variable, set to
+ 
  the value in the mapping
+ 
* `sensitive_env` is like `env`, but the values are never logged or
+ 
  output; this is to prevent accidental leaking of secrets
+
+ 
Both `env` and `sensitive_env` are optional.
+
+
+ 
## Default adapter
+
+ 
The `default_adapter` field can be set to the name of an adapter
+ 
in the `adapters` field. That adapter will be used if the `filters`
+ 
filters allow an event.
+
+ 
If `filters` isn't set, `default_adapter` is not used.
+
+
+ 
## Triggers
+
+ 
The `triggers` field contains a sequence conditions (filters) that are
+ 
used to decide if an adapter is to be run. A trigger has two fields:
+
+ 
* `filters` is a list of event filters, just like the top level
+ 
  `filters` field, with the same syntax, predicates, and meaning
+ 
* `adapter` names the adapter to run if the filters allow an event
+
+ 
If there are several triggers that are allowed, every adapter is run,
+ 
in sequence. If an earlier adapter run fails, the later ones are still
+ 
run. However, only the first error is returned to the CI broker.