Skip to content
Lightweight continuous integration for raw git repositories
Rust Shell
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
analysis
hooks
src
tests
.cinderella.toml
.gitignore
Cargo.lock
Cargo.toml
LICENSE
ProjectOutline.md
README.md

README.md

Cinderella CI

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).

Usage

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 repository.

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 -f or --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 repository as .cinderella.toml. It is a TOML file with one table per build pipeline. Common build pipelines are test or build. E.g. the following is a valid configuration file executing a test phase and a build-release phase.

[test]
commands = [
    "cargo test",
]

[build-release]
commands = [
    "cargo build --release",
]

All 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 followed by build-release. If an error occurs in any of the pipelines, execution will be aborted and the following pipelines will not be executed.

Variables

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 or tag
  • %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

Environment Variables

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.

Conditions

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.

E-Mail Notification

You can send e-mail notifications on build failures. For this, create a file called 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 = "recipient@example.com"
from = "noreply@example.com"
server = "example.com"
user = "example"
password = "password"

If Cinderella finds a config.toml file with a table email it will enable e-mail notifications. If you want to disable e-mail notifications again, delete the table email from your Cinderella configuration file or delete the whole Cinderella configuration file.

Encrypted Variables

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 stored in .cinderella/secrets.

In plaintext create a TOML file .cinderella/secrets.toml that looks as follows:

USERNAME = "my-user"
PASSWORD = "my-secret"

Optionally, you can add the plaintext file to your .gitignore. You can create an encrypted file .cinderella/secrets by running the following command from your project's root directory:

cinderella encrypt

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 secrets.toml) run:

cinderella decrypt

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.

Open Points

This is a list of open points that are subject to implementation:

  • allow cinderella to run with 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 Source and WorkingCopy
  • 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
You can’t perform that action at this time.