Getting started with Vexor


In order to start using Vexor you should have a GitHub or BitBucket account.

Sign up to Vexor

Vexor supports 3 popular source control providers: GitHub, BitBucket and GitLab. No matter which one you've signed up with, you can always connect another, as well as update your email address and name, on the Profile Settings page.

Profile settings

Team settings

Collaborators can be invited to your team on the "Users" page. Each user can be assigned with a role Admin or Developer. Developers cannot remove projects and add users to the team.

Team settings

Adding a project

There's a list of all repos imported from your connected accounts in the "Add project" section.

Projects list

To add a project and make a first build just press "Add". You'll be asked to specify a project's language while adding.

Adding a project

Then you'll be redirected to the freshly added project.

Project page

Project notification settings

You can choose on which occasions you will be notified about your project's build statuses. There're three available options:

Project notifications settings

Project settings

Secure env variables, SSH keys and build restrictions can be configured on project's "Settings" page.

Project settings page

Choosing project's language

Project's language can be changed here.

Project settings language

Configuring build restrictions

You can specify which branches you want to be built by a regular expression in the "Filter pushes" popup.

Project settings | Filter branches

We don't build pull requests from the same repo by default, because builds are already being initiated by pushes to a repo. This behavior can be changed by clicking on a "Build pull requests" checkbox (e.g. if you have filtered some branches but want to build all PRs). Pull requests from foreign repos are being built always, whether "Build pull requests" checkbox is on or not.

Configuring build statuses on GitHub or GitLab (no BitBucket, sorry)

Build statuses shown in pull requests could be configured here. Enabled by default.

Project settings | Build statuses

Canceling running builds after a push to the same branch

You might want ongoing builds to get cancelled after a push to the same branch. Enabled by default.

Project settings | Cancel builds

Configuring Slack notifications

Vexor can send build notifications to Slack channels. To enable this feature you should create an incoming webhook on the Slack integrations page and paste it to the "slack" section of the Vexor project settings page.

Project settings | Slack

Securing environment variables

You can add secure environment variables to your project (e.g. Heroku tokens, Code Climate keys, etc.). Note that env-vars which don't have to be secure could also be added via .vexor.yml config file.

Project settings | env vars

Adding SSH keys

Additional SSH keys can also be added through the interface. Note that you might want to keep keys in a particular order. User-added SSH keys are being added to the agent before the project's deploy key, ordered from most recent to earliest.

Project settings | SSH keys

Vexor config file

Project's config should be stored in vexor.yml (.vexor.yml works too) file in a root directory. For those who are migrating from Travis it is possible to use .travis.yml file but it's recommended to switch to vexor.yml config, because Vexor is not fully compatible with Travis and uses slightly different configuration options.

Available configuration keys

Common keys

language string

Specify a language so Vexor could run language-specific preparations for your project. If you don't have a Vexor config included in your repo's root, a default config will be used, which has only the language key based on a language you've chosen when added a repo to Vexor. If config file is empty, without language specified, your build won't we able to run.


language: ruby

env map

Set up your environment variables here. For secure env-vars see Configuring project ENV variables section. Environment config consists of three sections: global, exclude and matrix.

  - VAR1=some_stuff
  - VAR2="i'm a var with spaces"
  - SCRIPT=script_for_one_job
  - SCRIPT=script_for_another_job

Full example

  - RAILS_ENV=test
  - DATABASE_URL=postgresql://
  - SCRIPT="bundle exec rspec"
  - SCRIPT="bundle exec brakeman"
  - SCRIPT="bundle exec rubocop"

before_install array

A list of commands called before installation stage.

- echo called before installing any dependencies
- ... etc.

install array

By default we install a number of packages depending on a language specified at the beginning of your config file, including a language binary itself. Use this option to override this behavior.

- sudo apt-get install -y ruby-build rbenv
- rbenv install 2.1.2
- gem install bundler
- ... etc.

database array

A list of database-related configuration.

We already have Postgresql 9.4 (with postgres-contrib), MySQL 5.6, MongoDB 2.6.5 and Redis 3.0.2 installed in containers.

- psql -U postgres -c "create database test;"
– mysql -u root -e "create database test;"

Notice for Rails users: by default we're already running all necessary database configuration to get Rails tests working so in most cases you don't have to write any database configuration at all. Use database config only if you want to override this behavior.

before_script array

A list of commands called after installation and database stages but before running tests. Usually it's used to install additional dependencies when the system's environment's already configured (e.g you need to install additional gems etc.)

- sudo npm install bower
- sudo gem install brakeman

services array

Additional services you want to run in your container. For each specified service there will be sudo service #{specified_service} start command executed. Here you can see which services are already present in our image.

See Services for details about versions installed in our image.

Note: There's an alias for rabbitmq-server. You could simply write rabbitmq.

  - rabbitmq
  - redis-server

script string

You can override a command which runs tests. This might be useful together with matrix when you want to run your test in parallel.

  script: bundle exec rspec

workdir string

Your project's working directory. By default it's set to your repo's root directory (which is ~/org_name/project_name).

  workdir: relative_dir

timeout int

Job's maximum running time in seconds. Default is 1 hour.

    timeout: 1800

read_timeout int

If there wasn't any output within the read timeout (in seconds) a job will be shut down.

    read_timeout: 60


Enable/disable dependencies caching. True by default.

  cache: false

Directories caching:

You can download some packages before running tests and install them. To get away from downloading the package each time you can cache directory where it is located. Then delete "wget" from your config file and just "make" or "dpkg" your package at each run of tests.

    enabled: true
    - ~/my_deps1
    - /usr/local/my_deps2
    - .....

Language versions

Each of these keys usually gets a list of language versions which you want to run tests against. If you specified env:matrix, there will be versions_num * martix_size jobs. See Paralleism for better understanding.


- 1.9.3
- 2.0.0-p0
- 2.1.1


Cancel a build

You can cancel any build by clicking a "Stop" button on a build page. A particular job cannot be stopped.

Cancelling a build

Restart a build

Any finished build can be restarted.

If you want to restart a build without changing any build configuration, just click a "Rebuild" button on a build page.


In case you want to quickly test some configuration options out without commiting every vexor.yml change to a repo, you can use "Edit config" feature. Click "Edit config" button on a build page, modify your configuration and then click "Rebuild with new config" button. A new build will be created.

Rebuild with new config


One of the Vexor's main advantages is that it can run an unlimited amount of jobs in parallel. There're several ways to set up parallelim.

Running tests in parallel against different language versions.

You can specify different language versions (see Language versions for details) in vexor.yml config file. For each version there will be a job started.



  - 2.1.0
  - 2.0.0
  - 1.9.3
  - rbx-2


Parallelism | Capistrano example

Running a different script for each job

Parallel jobs can also be configured via env:matrix key in vexor.yml file. The basic idea is that you specify a script which depends on an environment variable and assign different values to this variable in the matrix section of a config file. Here's an example of how we're using this aproach to build the Vexor web app:

  - PROJECT=backend
  - PROJECT=frontend

script: bundle exec rake test:${PROJECT}

And here's a resulting build:

Parallelism | Vexor example

Here's another example of how to use matrix for build parallelization. We're gonna run Rspec, check security with Brakeman, check code quality with Rubocop and check our coffee, scss and haml files.

    - BUILD_CMD='rspec'
    - BUILD_CMD='rubocop'
    - BUILD_CMD='brakeman -z'
    - BUILD_CMD='haml-lint app/views/'
    - BUILD_CMD='scss-lint'
    - BUILD_CMD='rake coffeelint'
script: bundle exec ${BUILD_CMD}

Parallelism | Vexor 2 example

Combining language versions with a matrix

"Matrix" and "language versions" approaches can be combined. A resulting build will be containing versions_num * matrix_size jobs.


  - TEST_SUITE=test
  - TEST_SUITE=cucumber

- 2.2
- 2.1
- 2.0

And the result is:

Parallelism | Jekyll example

Parallel Rspec

There's another option for Rails users. You can specify a number of parallel jobs and set script to parallel_rspec to run automatically Rspec jobs in parallel.

parallel: 4
script: parallel_rspec

Preinstalled packages

There's a number of preinstalled packages in our image.


We already have xvfb installed and running in our image.


Version 9.4 with Contrib package is preinstalled and run automatically. Use login postgres without a password.

psql -U postgres -c "create database test;"


Version 5.6 is preinstalled and run automatically. Use login root without a password.

mysql -u root -e "create database test"


Version 3.2 is preinstalled.

  - mongodb


Version 3.0.2 is preinstalled and run automatically


Version 3.6.1 is preinstalled; to run, issue:

  - rabbitmq


Version 1.5.2 is preinstalled; to run, issue:

  - elasticsearch

You can use v2.1.1 also:

  - elasticsearch2


Version 2.1.1 is preinstalled


Version 2.2.10 is preinstalled

Language guides


In order to start ruby tests, you only need to specify the language:

language: ruby

In this simplest case the 2.0.0 ruby version will be used and these commands will be run:

install: bundle install
script: bundle exec rake

If you're using rails, you will need to setup the DB before running tests:

- bundle exec rake db:create db:migrate RAILS_ENV=test

You can specify additional bundler options:

bundler_args: --without debugger

You can also specify several different Gemfile versions, in this case a matrix will be created:

- Gemfile.mysql

These versions of ruby are available for testing:

To select the required version, use rvm key:

- 2.0
- 2.1
- head

When searching a ruby version, a fuzzy matching is used, so you don't need to strictly specify the versions. If for whatever reasons you need the version we don't have, you have ruby-build preinstalled on the build machine, so you can always compile the required version.

In order to save time when running tests, installed gems are cached. You can disable this with:

cache: false

We don't use rbenv or rvm to manage the ruby versions; all rubies are built as deb packages. When running your tests, the required ruby version is installed from the corresponding deb package. We don't have neither rbenv, nor rvm on the testing machine, but ruby-build is installed and can be used to compile the required version. The best option, however, will be to let us know which ruby version you need and we'll create the deb package for you.


To run Clojure apps you should issue:

language: clojure

Leiningen 2.3.4 is preinstalled in image; 1.x isn't supported; symlink lein -> lein2 is included for Travis compatibility.

These commands will be run:

lein deps
lein test

You can set your custom command to run the tests:

script: lein midje

You can specify a different version of the JDK

  - openjdk7
  - oraclejdk7

JDKs preinstalled in image include

Java 6 isn't included.


To run Scala apps issue:

language: scala

Scala 2.10.3 is used by default.

Because of Scala's versions multitude and incompatibilities it's not preinstalled in image. Instead, sbt-extras is used together with caching. sbt-extras detects and automatically installs the required version sbt which, in turn, manages the version of the language. Everything is being installed and set up during the first run, then works fast because of caching.

Testing is run with these commands:

sbt ++$SCALA_VERSION update
sbt ++$SCALA_VERSION test

Scala and Java versions can be managed:

  - 2.10.2
  - 2.10.3

  - openjdk7
  - oraclejdk7

JDKs preinstalled in image include

Java 6 isn't included.

Caching is turned on automatically when you use Scala. To turn it off set:

cache: false


In order to run tests for a python project you need to specify the language:

`language: python`

python version 2.7 will be used for running the tests and the following commands will be run:

  virtualenv ~/.python-virtualenv
  source ~/.python-virtualenv/bin/activate

  pip install -r [Rr]equirements.txt
  python install

  python test
  # or
  python test
  # or

These versions of python are available

To select a specific version for testing, a python config key should be used:

- 2.7
- pypy-2

When searching the python version, fuzzy matching is used, which first tries to find a match strictly, and then falls back to the closest version if not found.


In order to run the nodejs tests, you need to specify:

language: node_js

In this case the version 0.10.29 will be used and the following commands will be run:

install: npm install
script: npm test

These versions of nodejs are available for testing

To select the specific version for testing, a configuration key node_js is used

- "0.9"
- "0.10"

When searching the nodejs version, fuzzy matching is used, which first tries to find a match strictly, and then falls back to the closest version if not found.

Build machine has phantomjs 1.9.7 preinstalled, which you can use for headless testing.


In order to run tests for a go project you need to specify the language:

`language: go`

go version 1.2.2 will be used for running the tests and the following commands will be run:

install: go get -v ./...
script: go test -v ./...

These versions of go are available

To select a specific version for testing, a go config key should be used:

- 1.1
- 1.3
- tip

When searching the go version, fuzzy matching is used, which first tries to find a match strictly, and then falls back to the closest version if not found.


In order to run the rust tests, you need to specify:

language: rust

In this case the version 0.11 will be used and the following commands will be run:

- git submodule init
- git submodule update

script: make

These versions of rust are available for testing

To select the specific version for testing, a configuration key rust is used

- 1.2.0

Deploiyng your application

To deploy your application, you can use the standard tools of language or environment. For instance, Capistrano or Mina are usually used to deliver Rails applications.

The new version of the application is normally delivered to the server only if all the tests pass successfully. There is a special deploy phase in the configuration file of Vexor. Using it you can call user commands after successfully passing the tests. This phase is started by a separate task, and all artefacts that could occur during the tests are ignored.

# vexor.yml:
  - branch: master
      - bundle exec cap production deploy

This example shows the easiest way to deliver Rails applications.

The deploy section of the configuration file can contain the unlimited number of branches for the deploy. It is also possible to skip some steps from the main thread of execution, for example:

# vexor.yml
language: ruby
rvm: 2.5

install: bundle install
database: bundle exec rake db:setup
script: bundle exec rspec

  - branch: master
      - install
      - database
    - bundle exec cap production deploy
    - echo "Done"

During the deploy phase in the new container the optional stages of installation and preparation of the database will be skipped, which can significantly speed up the deploy time.


Vexor has the postpaid billing system. The price is calculated from the total time spent for running tests. Any time you can check how much time your tasks took during the current month. You can also view Vexor usage details during any month in the past.

Balance page

Moreover, in your personal account you can view your current balance and discount info. You can change the payment details, and view the information about your past payments. Different types of reports are available - from daily to monthly ones. It is also possible to set up automatic payments and fill in your company contact information.

Invoice details