Cinderella CI is a simple Continuous Integration solution for git repositories. It is designed for people who do not want to work with big solutions like Gitlab or Jenkins and probably also work with standard bare git repositories (instead of Gitlab, gitea or similar).
Cinderella expects a
.cinderella.toml file with the CI configuration in the
root folder of your repository. When you execute Cinderella with the clone URL
of a git repository it will clone the URL into a temporary folder, search for
the CI configuration file and if available execute the build steps.
There is a sample hook in
hooks/post-update which you can use in your remote
repository to execute Cinderella automatically each time you push to your
You can also manually execute Cinderella. To do so pass it the path to your git repository and optionally the name of the branch you want to build:
cinderella run https://github.com/aufziehvogel/Cinderella.git --branch master
You can also build a specific tag with:
cinderella run https://github.com/aufziehvogel/Cinderella.git --tag 0.1.0
You can use a different path than
.cinderella.toml for your CI configuration
file with the argument
--file. This argument is evaluated relatively
to the git work directory. If you want to use a CI configuration file local
to your shell directory use absolute paths.
cinderella run https://github.com/aufziehvogel/Cinderella.git --file /home/user/cinderella-test.toml
CI Configuration Format
The CI configuration file has to be saved to the root directory of your
It is a TOML file with one table per build pipeline.
Common build pipelines are
build. E.g. the following is a valid
configuration file executing a
test phase and a
[test] commands = [ "cargo test", ] [build-release] commands = [ "cargo build --release", ]
commands are executed as programs, i.e. no shell is involved. If you
want to execute one or multiple commands in a shell you have to call the
desired shell manually.
Pipelines are executed in the order in which they are defined. For the
given configuration file it is ensured that first
test is being executed
build-release. If an error occurs in any of the pipelines,
execution will be aborted and the following pipelines will not be executed.
You can use variables in the configuration file. All variables are denoted
with a percentage symbol (
%) and will be replaced before the commands
are being sent to the shell.
Currently supported variables are:
%REFTYPE: The type of reference that is built,
%BRANCH: The name of the branch that is built, if it is a branch
%TAG: The name of the tag that is built, if it is a tag
It is possible to use environment variables in your commands, e.g.
commands = ["echo $HOME"]. Cinderella will substitute them by their
values before the command gets sent to the operating system.
This is also true if you use
bash or other shells in your commands list.
This means that in such cases the plaintext value of the environment
variable will be visible in your shell history.
You can conditionally execute a pipeline with the
when option, for example
to run a pipeline only for specific branches:
[build-release] commands = [ "cargo build --release", ] when = "\"%BRANCH\" == \"master\""
The condition will be executed with the Rust library evalexpr.
You can send e-mail notifications on build failures. For this, create a file
config.toml in the same directory as your Cinderella executable with
the following content (this file is called Cinderella configuration file
to distinguish it from the CI configuration file):
[email] to = "firstname.lastname@example.org" from = "email@example.com" server = "example.com" user = "example" password = "password"
If Cinderella finds a
config.toml file with a table
Warning: I am not security expert and there has been no analysis regarding
the security of my implementation. I am using
sodiumoxide internally, but
still I could do something wrong. If you want to use this feature on a public
repository, please review my implementation. I personally only use it for
internal repositories at the moment. If you find any vulnerabilities in my
implementation please tell me.
Sometimes a script needs to use credentials that you do not want to store in
a version control system in plaintext. For this use case, Cinderella supports
the storage of variables in an encrypted file. This file has to be
In plaintext create a TOML file
.cinderella/secrets.toml that looks as
USERNAME = "my-user" PASSWORD = "my-secret"
Optionally, you can add the plaintext file to your
You can create an encrypted file
.cinderella/secrets by running the
following command from your project's root directory:
After this step you may delete the
secrets.toml if you want.
You can now use the variables in your build commands:
[build-release] commands = [ ".cinderella/upload-to-ftp.sh %USERNAME %PASSWORD", ]
To decrypt the encrypted file (and re-create
The password you chose during encryption has to be set in the Cinderella configuration file (this means that you have to use the same password for all projects you test and build with Cinderella):
[secrets] password = "my-secret-for-decryption"
Of course, this means that an attacker on your server can decrypt all your secrets. Secret encryption only ensures that credentials are not stored in your repository in cleartext, but as soon as your server is compromised all your credentials are compromised.
This is a list of open points that are subject to implementation:
- allow cinderella to
runwith a non-git folder: Logic should be so that user passes a URL or a path to
run(same as now) and Cinderella checks if this is a URL, a local git repository or a local folder without git and then runs the correct
- introduce command shortcuts for commands that are often used but annoying
to write in their full form
"[bash] foo && bar"for
"bash -c \"foo && bar\""
"[python-venv env] pip install -r requirements.txt && ./foo"for
"bash -c \"source env/bin/activate && pip install -r requirements.txt && ./foo\""
- keep a status of the last result per repository (to send OK again mails)
- send a more detailed error message on the build error reason:
- return code of the failed command
- full log of the executed commands (in a prompt style, command followed by output)
- send a mail with all compiler warnings? (or optionally to be enabled/disabled in .cinderella.toml?); otherwise developers never see the warnings