README.md (9431B)
1 Cinderella CI 2 ============= 3 4 Build Status:  5 6 Cinderella CI is a simple Continuous Integration solution for git repositories. 7 It is designed for people who do not want to work with big solutions like 8 Gitlab or Jenkins and probably also work with standard *bare* git repositories 9 (instead of Gitlab, gitea or similar). 10 11 Cinderella is a single binary that currently executes all builds directly 12 on the same machine. Positive: It ships as a single binary with dependencies 13 only to standard libraries like libc. It does not require Docker or similar. 14 Negative: Testing with a clean, bare OS is currently not in focus. It's 15 probably possible by starting up a fresh VM, copying cinderella onto it and 16 then executing it, but it's more effort on your side. 17 18 19 Usage 20 ----- 21 22 Cinderella expects a `.cinderella.toml` file with the CI configuration in the 23 root folder of your repository. When you execute Cinderella with the clone URL 24 of a git repository it will clone the URL into a temporary folder, search for 25 the CI configuration file and if available execute the build steps. 26 27 There is a sample hook in `hooks/post-update` which you can use in your remote 28 repository to execute Cinderella automatically each time you push to your 29 repository. 30 31 You can also manually execute Cinderella. To do so pass it the path to your 32 git repository and optionally the name of the branch you want to build: 33 34 ```bash 35 cinderella run https://github.com/aufziehvogel/Cinderella.git --branch master 36 ``` 37 38 You can also build a specific tag with: 39 40 ```bash 41 cinderella run https://github.com/aufziehvogel/Cinderella.git --tag 0.1.0 42 ``` 43 44 You can use a different path than `.cinderella.toml` for your CI configuration 45 file with the argument `-f` or `--file`. This argument is evaluated relatively 46 to the git work directory. If you want to use a CI configuration file local 47 to your shell directory use absolute paths. 48 49 ```bash 50 cinderella run https://github.com/aufziehvogel/Cinderella.git --file /home/user/cinderella-test.toml 51 ``` 52 53 54 Configuration Files 55 ------------------- 56 57 Cinderella uses two configuration files: 58 59 - **CI Configuration File**: The CI configuration file is usually called 60 `.cinderella.toml` and belongs to the project 61 that should be built. It defines under which circumstances Cinderella should 62 build the project (e.g. only tags, only specific branches) and which 63 commands the Cinderella engine has to execute to run the build. Without 64 this file, Cinderella will not run a build for the project. 65 - **Cinderella Configuration File**: The Cinderella configuration file belongs 66 to your Cinderella instance. It is usually called `config.toml` and is 67 located in the same folder as your Cinderella executable. It specifies 68 parameters that Cinderella needs to perform actions like sending e-mails, 69 writing output files or decrypting secrets. This file is optional. 70 71 72 CI Configuration Format 73 ----------------------- 74 75 The *CI configuration file* has to be saved to the root directory of your 76 repository as `.cinderella.toml`. 77 It is a TOML file with one table per build pipeline. 78 Common build pipelines are `test` or `build`. E.g. the following is a valid 79 configuration file executing a `test` phase and a `build-release` phase. 80 81 ```toml 82 [test] 83 commands = [ 84 "cargo test", 85 ] 86 87 [build-release] 88 commands = [ 89 "cargo build --release", 90 ] 91 ``` 92 93 All `commands` are executed as programs, i.e. no shell is involved. If you 94 want to execute one or multiple commands in a shell you have to call the 95 desired shell manually. 96 97 Pipelines are executed in the order in which they are defined. For the 98 given configuration file it is ensured that first `test` is being executed 99 followed by `build-release`. If an error occurs in any of the pipelines, 100 execution will be aborted and the following pipelines will not be executed. 101 102 ### Variables 103 104 You can use variables in the configuration file. All variables are denoted 105 with a percentage symbol (`%`) and will be replaced before the commands 106 are being sent to the shell. 107 Currently supported variables are: 108 109 - `%REFTYPE`: The type of reference that is built, `branch` or `tag` 110 - `%BRANCH`: The name of the branch that is built, if it is a branch 111 - `%TAG`: The name of the tag that is built, if it is a tag 112 113 ### Environment Variables 114 115 It is possible to use environment variables in your commands, e.g. 116 `commands = ["echo $HOME"]`. Cinderella will substitute them by their 117 values before the command gets sent to the operating system. 118 119 This is also true if you use `bash` or other shells in your commands list. 120 This means that in such cases the plaintext value of the environment 121 variable will be visible in your shell history. 122 123 ### Conditions 124 125 You can conditionally execute a pipeline with the `when` option, for example 126 to run a pipeline only for specific branches: 127 128 ```toml 129 [build-release] 130 commands = [ 131 "cargo build --release", 132 ] 133 when = "\"%BRANCH\" == \"master\"" 134 ``` 135 136 The condition will be executed with the Rust library 137 [evalexpr](https://docs.rs/evalexpr/5.0.5/evalexpr/index.html). 138 139 140 E-Mail Notification 141 ------------------- 142 143 You can send e-mail notifications on build failures. For this, create a file 144 called `config.toml` in the same directory as your Cinderella executable with 145 the following content (this file is called *Cinderella configuration file* 146 to distinguish it from the CI configuration file): 147 148 ```toml 149 [email] 150 to = "recipient@example.com" 151 from = "noreply@example.com" 152 server = "example.com" 153 user = "example" 154 password = "password" 155 ``` 156 157 If Cinderella finds a `config.toml` file with a table `email` it will enable 158 e-mail notifications. If you want to disable e-mail notifications again, 159 delete the table `email` from your Cinderella configuration file or delete 160 the whole Cinderella configuration file. 161 162 163 Encrypted Variables 164 ------------------- 165 166 **Warning:** I am not security expert and there has been no analysis regarding 167 the security of my implementation. I am using `sodiumoxide` internally, but 168 still I could do something wrong. If you want to use this feature on a public 169 repository, please review my implementation. I personally only use it for 170 internal repositories at the moment. If you find any vulnerabilities in my 171 implementation please tell me. 172 173 Sometimes a script needs to use credentials that you do not want to store in 174 a version control system in plaintext. For this use case, Cinderella supports 175 the storage of variables in an encrypted file. This file has to be 176 stored in `.cinderella/secrets`. 177 178 In plaintext create a TOML file `.cinderella/secrets.toml` that looks as 179 follows: 180 181 ```toml 182 USERNAME = "my-user" 183 PASSWORD = "my-secret" 184 ``` 185 186 Optionally, you can add the plaintext file to your `.gitignore`. 187 You can create an encrypted file `.cinderella/secrets` by running the 188 following command from your project's root directory: 189 190 ```bash 191 cinderella encrypt 192 ``` 193 194 After this step you may delete the `secrets.toml` if you want. 195 196 You can now use the variables in your build commands: 197 198 ```toml 199 [build-release] 200 commands = [ 201 ".cinderella/upload-to-ftp.sh %USERNAME %PASSWORD", 202 ] 203 ``` 204 205 To decrypt the encrypted file (and re-create `secrets.toml`) run: 206 207 ```bash 208 cinderella decrypt 209 ``` 210 211 The password you chose during encryption has to be set in the *Cinderella 212 configuration file* (this means that you have to use the same password for 213 all projects you test and build with Cinderella): 214 215 ```toml 216 [secrets] 217 password = "my-secret-for-decryption" 218 ``` 219 220 Of course, this means that an attacker on your server can decrypt all your 221 secrets. Secret encryption only ensures that credentials are not stored in your 222 repository in cleartext, but as soon as your server is compromised all your 223 credentials are compromised. 224 225 226 Badges 227 ------ 228 229 It's possible to generate build success/failure badges that can be displayed 230 on websites. To enable this feature add the following configuration: 231 232 ```toml 233 [dashboard] 234 folder = "/var/www/cinderella" 235 ``` 236 237 The build process will then write the badges into `folder`. Serving the data 238 via HTTP is your own responsibility, use any web server of your choice. 239 240 241 Open Points 242 ----------- 243 244 This is a list of open points that are subject to implementation: 245 246 - use virtual machines to execute unit tests, e.g. 247 [using qemu](https://stackoverflow.com/questions/3146013/qemu-guest-automation) 248 (a more high level abstraction like libvirt or vagrant would probably be 249 simpler, but I'd prefer low-level) 250 - add more system tests 251 - improve stability and error messages (sometimes I receive a rust crash 252 due to a failed expect/unwrap) 253 - keep a status of the last result per repository (to send *OK again* mails) 254 - allow cinderella to `run` with a non-git folder: Logic should be so that 255 user passes a URL or a path to `run` (same as now) and Cinderella checks 256 if this is a URL, a local git repository or a local folder without git and 257 then runs the correct `Source` and `WorkingCopy` 258 - introduce command shortcuts for commands that are often used but annoying 259 to write in their full form 260 - `"[bash] foo && bar"` for `"bash -c \"foo && bar\""` 261 - `"[python-venv env] pip install -r requirements.txt && ./foo"` for 262 `"bash -c \"source env/bin/activate && pip install -r requirements.txt && ./foo\""` 263 - send a mail with all compiler warnings? (or optionally to be 264 enabled/disabled in .cinderella.toml?); otherwise developers never see the 265 warnings