044-ci-system.rst (3538B)
1 DD 44: CI System 2 ################ 3 4 Summary 5 ======= 6 7 This documents describes Taler's CI system based on Buildbot. 8 9 This document uses `RFC 2119 <https://tools.ietf.org/html/rfc2119>`_ 10 keywords throughout. 11 12 Motivation 13 ========== 14 15 With the current CI system there are an array of issues: 16 17 - Central place for all the jobs. 18 - The central config is poorly organized. 19 - We should prefer to keep as much CI logic in respective project source repos 20 as possible. 21 - Jobs should be split up further to allow for more granular control and 22 insight. 23 - Job triggers are unclear. 24 - The build environments are mutable. 25 - Non-trivial and error-prone to keep track of environment state. 26 - Hard to get an overview of what repo is causing a failure, at a quick glance. 27 - Bad for development workflow on a single project when you are getting 28 false-negatives all the time. 29 30 Proposed Solution 31 ================= 32 33 General 34 ------- 35 36 Jobs shall be executed inside of containers. 37 38 One build pipeline (aka. "builder") per repo. 39 40 Build steps are generated from directory structure within a given repo. 41 42 Example directory structure: 43 44 :: 45 46 contrib 47 └── ci 48 ├── ci.sh 49 ├── Containerfile 50 └── jobs 51 ├── 0-codespell 52 │ ├── config.ini 53 │ ├── dictionary.txt 54 │ └── job.sh 55 ├── 1-build 56 │ ├── build.sh 57 │ └── job.sh 58 └── 2-docs 59 ├── docs.sh 60 └── job.sh 61 62 Job directories **MUST** follow this pattern: 63 ``<repo_root>/contrib/ci/jobs/<n-job_name>/`` 64 65 ``n`` is an integer used for ordering the build steps. 66 67 Job directories **MUST** contain a script named ``job.sh`` which **MAY** 68 execute other scripts. 69 70 Config files may optionally be created, and MUST be named ``config.ini`` and 71 placed in the job directory. 72 73 Available config options: 74 75 :: 76 77 [build] 78 HALT_ON_FAILURE = True|False 79 WARN_ON_FAILURE = True|False 80 CONTAINER_BUILD = True|False 81 CONTAINER_NAME = <string> 82 CONTAINER_ARCH = <string> 83 84 85 Unless *all* jobs specify a "CONTAINER_NAME" in their custom config a 86 container file **MUST** be present at ``<repo_root>/contrib/ci/Containerfile``. 87 The container file will be built and used to run all of a repo's jobs 88 by default. 89 90 All projects SHOULD have a ``build`` step and a ``test`` step, at a minimum. 91 92 Running CI Locally 93 ------------------ 94 95 Running the CI scripts locally can be useful for development and testing. 96 97 Included in each CI directory is a script which simplifies running jobs 98 in the same way the CI Worker does, in containers, using ``podman``. 99 100 :: 101 102 # Usage: 103 ./contrib/ci/ci.sh <job-name> 104 105 # For example, if the CI jobs tree looks like this: 106 ./contrib/ci/jobs 107 ├── 0-codespell/ 108 ├── 1-build/ 109 ├── 2-test/ 110 ├── 3-docs/ 111 ├── 4-deb-package/ 112 └── 5-deploy-package/ 113 114 # Then you can run job '0-codespell' as follows: 115 ./contrib/ci/ci.sh 0-codespell 116 117 # If you are using podman and have "qemu-user-binfmt" installed 118 # then you may attempt to run any job under an alternative CPU 119 # architecture by providing a second argument. 120 # For example: 121 ./contrib/ci/ci.sh 0-codespell arm64 122 123 124 Additional Builders 125 ------------------- 126 127 To run some tests there is a need for many or most project's sourcecode to be 128 available in the same environment. This will be a separate builder/pipeline 129 from the per-repo builders. Triggers for this builder are yet to be 130 determined.