Basic Commands

There are three main operations you can perform with Rultor: merge, deploy and release. Every call to Rultor is posted in a Github issue as a comment (yes, any Github issue, in any Github project!)

Commands must start with @rultor followed by command text.

For example, in a pull request that is ready to be merged you post a new comment saying, literally:

@rultor please check and merge this pull request

It is important to start a command with @rultor and mention merge somewhere in the text. All the rest is ignored. You can achieve exactly the same thing by just posting:

@rultor merge

BTW, by default, only Github project collaborators can talk to Rultor, although it is configurable.

Rultor assigns a unique ID to every build. Build log URLs are created using this IDs. Every Github comment has a unique number and in Rultor each "talk"(a Github issue, for example) has a unique number. Rultor build ID is combination of these two numbers. Take this build for example: http://www.rultor.com/t/11509-297164344. Here, 11509 is unique ID of the build inside the talk and 297164344 is the talk number. There is no gaurantee that the build number will go consequentially.

Merge

It is a very good practice, to run your automated build after merging a pull request into the master branch and right before pushing changes. When your pull request is ready, ask Rultor to merge it. Rultor will checkout your master branch, merge changes into it, run the automated build, and push the new version of master to your repo. "Master Branch Must Be Read-Only" article explains why it is important to use this mechanism and protect your master against accidental failures.

Don't forget to create .rultor.yml in the root directory of your repository and configure the build automation script there. For example:

merge:
  script: mvn clean install

If you don't configure it, Rultor will try to guess your build automation tool and call it accordingly. If you have pom.xml in your root directory — it is Maven; if you have Gemfile — it is Bundler, etc.

We strongly recommend that you configure your script in .rultor.yml.

Deploy

Deployment is when you place a packaged artifact into your production (or test) environment in order to make it available for end-users (or testers). Different systems deploy themselves differently — Rultor makes it possible to automate any possible scenario.

All you need to do is define your deployment scenario as a bash script and configure it in .rultor.yml.

For example, this is how we deploy Rultor itself (see our .rultor.yml file):

deploy:
  env:
    MAVEN_OPTS: "-XX:MaxPermSize=256m -Xmx1g"
  script:
    - "sudo bundle"
    - "mvn clean deploy -Prultor --settings ../settings.xml"
    - "mvn clean site-deploy -Psite -Prempl --settings ../settings.xml"

First, we install all Ruby gems required for Jekyll (this is how this website is built). Then, we deploy the system to CloudBees. Then, we deploy the site to Github Pages.

Release

Release is when you package a stable version of your product and make it available for everybody in an artifact repository. For example, Maven Central or RubyGems.

The Release command automates this for you. The command does require one mandatory argument, though. You should call it like this:

@rultor release, tag=`1.7`

Then, in your script you get $tag environment variable, which will be set to 1.7. Your script should change the version of the product to 1.7 and build it.

This is how we do it in jcabi rultor.yml. For example:

release:
  script: |
    mvn versions:set "-DnewVersion=$tag"
    git commit -am "$tag"
    mvn clean deploy -Pqulice -Psonatype -Pjcabi
    mvn clean site-deploy -Psite -Prempl --settings ../settings.xml

We change the version of the product to the one provided in $tag, then commit the changes, build and deploy to Sonatype. Next, we build the project site and deploy it to Github Pages. All the rest is done by Rultor. Basically, this is what will be done:

Check out your repository
Run the script configured in .rultor.yml
Tag the latest commit as $tag
Push the new tag to the repository

Of course, if any of these steps fails, the entire command fails and you get a full log in the Github issue.