Rultor is configured solely through the YAML
.rultor.yml file stored in the
root directory of your Github repository. There is no control or management
panel. Everything you want to say to Rultor is placed into your
file. The file is mandatory, but all content is optional.
This page contains a complete reference of YAML instructions in alphabetic order.
You may wish to define a role of an architect in your project, who will supervise all merge/release/deploy commands. No command of that kind will be executed without his confirmation:
architect: - yegor256
This is enough to tell Rultor to ask for confirmation before running a build.
Very often, you want to add secret files to the directory of your build, right before it starts. For example, a file with database credentials that should be deployed to production. You don't want to keep this file in the main repository since it contains sensitive information, not intended to be accessible by all programmers.
Put it into another private Github repository and inform Rultor that he has to fetch it from there:
assets: secret.xml: "yegor256/secret-repo#assets/settings.xml"
This configuration tells Rultor that it needs to fetch
yegor256/secret-repo and place it into the
secret.xml file right before
starting a build.
Keep in mind that every builds starts in
while assets are placed one folder up in the directory tree,
/home/r. This is how the directory layout looks:
/home /r run.sh pid status stdout secret.xml /repo .rultor.yml pom.xml ...your other files...
Don't forget to add @rultor to the list of collaborators in your private repository. Otherwise Rultor won't be able to fetch anything from it.
The repository you're fetching assets from must contain
friends section should include the name of repository where
these assets are used, for example:
friends: - yegor256/rultor - jcabi/*
You may want to keep your secret assets right inside your main repository. In this case, in order to keep them secret, you should encrypt them using rultor remote:
$ gem install rultor $ rultor encrypt -p me/test secret.txt
me/test is the name of your Github project.
This code encrypts
secret.txt file. You will get a new file
Commit this file to your repository — nobody will be able
to read it, except Rultor server itself.
Then, instruct Rultor to decrypt it before running your build:
decrypt: secret.txt: "repo/scrt/secret.txt.asc"
This configuration tells Rultor to get
scrt/secret.txt.asc from the
root directory of your repository, decrypt it and save the result
secret.txt. You can access it from your script as
In other words, you can access it at
to the repository root from where your script is executed.
The default Docker image used for all commands is
You can change it to, say,
docker: image: "ubuntu:12.10"
You can also use your own
Dockerfile and build your own Docker image,
right before the build. Put
Dockerfile in some directory in the repository
together with all other Docker files (if you need them) and provide a location
of that directory:
docker: directory: repo/my-docker-image
You can specify environment variables common for all commands, for example:
env: MAVEN_OPTS: "-XX:MaxPermSize=256m -Xmx1g" merge: script: - "mvn clean install" deploy: script: - "mvn clean deploy"
In this example,
MAVEN_OPTS environment variable will be set
for merging and deploying commands.
You can specify script instructions common for all commands, for example:
install: - "sudo apt-get install texlive" merge: script: - "latex ..." deploy: script: - "latex ..."
In this example,
texlive package will be installed before merge
and before deploy commands execution.
By default, anyone can see your build logs. This may not be desired for private projects. To grant access to your logs only for a selected list of users, use this construct:
readers: - "urn:github:526301" - "urn:github:8086956" - ...
Every user is specified as a URN, where his Github account number
stays right after
urn:github:. You can get your Github account number
by logging into www.rultor.com
and moving mouse over your name, at the
top of the page.
Run As Root
By default, we create a new user
r in Docker container and
run your scripts from it. You can instruct Rultor to run
everything as root:
docker: as_root: true
This may be a useful option when you are using a custom Docker
container with something different from Ubuntu inside. Switching
to a user
r may not work smoothly under CentOS, for example. In
this case, just use root.
By default, Rultor uses its own servers to run your builds. You can change that by providing your own SSH coordinates:
ssh: host: test.example.com port: 22 key: ./keys/id_rsa login: test
Your servers must have
docker installed. This is the only requirement.
Merge, Deploy, Release
configured similarly in
.rultor.yml. For example:
merge: # or "deploy" or "release" commanders: - jeff - walter env: MAVEN_OPTS: "-XX:MaxPermSize=256m -Xmx512m" script: - "sudo apt-get install graphviz" - "mvn clean install"
Environment variables have to be configured, as an associative array with names
of variables as keys, in the
Executable script is configured as a list of texts. They will be executed one by one. If any of them fails, execution stops.
The list of Github accounts able to give commands to Rultor is specified in
commanders. By default, only Github repository collaborators can give
commands. Configured commanders don't replace collaborators. In other words,
Github collaborators and accounts mentioned here are allowed to give commands.
There are a few additional configurable parameters for
merge: script: | echo "testing..." echo "building..." echo "packaging..." squash: true fast-forward: default
squash option may be set to
fast-forward may be either
--ff argument for Git),
More information about it here.
rebase option may be set to
false (default). If it's set
true, your fork branch will be "rebased" from origin before the merge.
When you need some script to be executed at the end of
every command (no matter what the result of that command is),
you can configure it via
install: | # create a new EC2 instance merge: script: | # use EC2 instance for testing uninstall: | # destroy EC2 instance
This mechanism can be useful when you want to free certain resources, created during installation.