summaryrefslogtreecommitdiff
path: root/contrib/cirrus/CIModes.md
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/cirrus/CIModes.md')
-rw-r--r--contrib/cirrus/CIModes.md129
1 files changed, 129 insertions, 0 deletions
diff --git a/contrib/cirrus/CIModes.md b/contrib/cirrus/CIModes.md
new file mode 100644
index 000000000..8b1e33bb1
--- /dev/null
+++ b/contrib/cirrus/CIModes.md
@@ -0,0 +1,129 @@
+The following is a list (incomplete) of the primary contexts and runtime
+"modes" supported by podman CI. Note that there may be additional checks
+done regarding "skipping work" in the `runner.sh` script. This document
+only details the controls at the `.cirrus.yml` level.
+
+## Visualization
+
+The relationship between tasks can be incredibly hard to understand by
+staring at the YAML.
+[A tool exists](https://github.com/containers/automation/tree/main/cirrus-task-map)
+for producing a graph (flow-chart) of the `.cirrus.yml` file. A (possibly
+outdated) example of it's output can be seen below:
+
+![cirrus-task-map output](https://github.com/containers/podman/wiki/cirrus-map.svg)
+
+## Implementation notes
+
++ The `skip` conditional should never be used for tasks.
+ While it's arguably easier to read that `only_if`, it leads to a cluttered
+ status output that's harder to page through when reviewing PRs. As opposed
+ to `only_if` which will bypass creation of the task (at runtime) completely.
+ Also, by sticking to one conditional style, it's easer to re-use the YAML
+ statements across multiple tasks.
+
++ The only variables which can be used as part of conditions are defined by
+ Cirrus-CI.
+ [The list is documented](https://cirrus-ci.org/guide/writing-tasks/#environment-variables). Reference to any variables defined in YAML will **not** behave how
+ you expect, don't use them!
+
+* Somme Cirrus-CI defined variables contain non-empty values outside their
+ obvious context. For example, when running for a PR a task will have
+ `$CIRRUS_BRANCH` set to `pull/<number>`.
+
+* Conditions which use positive or negative regular-expressions have several
+ "flags" set: "Multi-line" and "Case-insensitive".
+
+## Testing
+
+Executing most of the modes can be mocked by forcing values for (otherwise)
+Cirrus-CI defined variables. For example `$CIRRUS_TAG`. As of the publishing
+of this document, it's not possible to override the behavior of `$CIRRUS_PR`.
+
+## Cirrus Task contexts and runtime modes
+
+### Intended general PR Tasks (*italic*: matrix)
++ ext_svc_check
++ automation
++ *build*
++ validate
++ bindings
++ swagger
++ consistency
++ *alt_build*
++ osx_alt_build
++ docker-py_test
++ *unit_test*
++ apiv2_test
++ *compose_test*
++ *local_integration_test*
++ *remote_integration_test*
++ *container_integration_test*
++ *rootless_integration_test*
++ *local_system_test*
++ *remote_system_test*
++ *rootless_remote_system_test*
++ *buildah_bud_test*
++ *rootless_system_test*
++ rootless_gitlab_test
++ *upgrade_test*
++ meta
++ success
++ artifacts
+
+### Intended for PR w/ "release" or "bump" in title:
++ (All the general PR tasks above)
++ release_test
+
+### Intended `[CI:DOCS]` PR Tasks:
++ ext_svc_check
++ automation
++ *build*
++ validate
++ swagger
++ consistency
++ meta
++ success
+
+### Intend `[CI:BUILD]` PR Tasks:
++ ext_svc_check
++ automation
++ *build*
++ validate
++ consistency
++ *alt_build*
++ osx_alt_build
++ test_image_build
++ meta
++ success
++ artifacts
+
+### Intended Branch tasks (and Cirrus-cron jobs, except "multiarch"):
++ ext_svc_check
++ *build*
++ swagger
++ *alt_build*
++ osx_alt_build
++ *local_system_test*
++ *remote_system_test*
++ *rootless_remote_system_test*
++ *rootless_system_test*
++ meta
++ success
++ artifacts
+
+### Intended for "multiarch" Cirrus-Cron (always a branch):
++ ext_svc_check
++ image_build
++ meta
++ success
+
+### Intended for new Tag tasks:
++ *build*
++ swagger
++ *alt_build*
++ osx_alt_build
++ meta
++ success
++ artifacts
++ release