Use CI environments locally. Not quite a vagrant.

We use Gitlab-CI to run CI for our projects, using Docker containers.

In certain situations, it can be helpful to set up an environment identical to a CI node on your local machine. rascal allows you to do just that by parsing your CI config (currently only .gitlab-ci.yml), starting required services and bringing up a Docker container.

Installation

Install with

$ gem install rascal

Caveats

This is an early alpha version. Use at your own risk.

Only the parsing of .gitlab-ci.yml is currently supported, and only a subset of the possible syntax will be properly interpreted.

Usage

You need to add some extra information to your .gitlab-ci.yml. A working version might look like this:

# settings here override job settings
.rascal: # add rascal specific config here
repo_dir: /repo # /repo is the default
variables: # extra env variables
BUNDLE_PATH: /cache/bundle
volumes: # mount these volumes
cache: /cache # we will always mount a /builds volume
before_shell:
- bundle check # run this when starting a shell
jobs:
rspec: # override settings for a specific job
variables:
BUNDLE_GEMFILE = /repo/Gemfile
.environment: &environment
image: registry.makandra.de/makandra/ci-images/test-env:2.5
services:
- name: registry.makandra.de/makandra/ci-images/pg:9.5
alias: pg-db
- name: registry.makandra.de/makandra/ci-images/redis:4
alias: redis
before_script:
- ruby -v
- bundle install
- bundle exec rake db:create db:schema:load
variables:
BUNDLE_PATH: ./bundle/vendor
DATABASE_URL: postgresql://pg_user@pg-db/test-db
REDIS_URL: redis://redis
PROMPT: CI env
cache:
paths:
- ./bundle/vendor
# ============= Actual jobs ================
rspec:
<<: *environment
script:
- bundle exec rake knapsack:rspec
parallel: 4

Then, in your project root, run rascal shell rspec.

Commands

rascal shell

Start a docker container (plus required services) and open an interactive shell.

Currently requires a "bash" to exist.

rascal run --

Run a single command in a docker container (plus required services), then exit with the command's exit status.

rascal run rspec -- bundle exec rspec spec/models/user_spec.rb

Unlike rascal shell, this allocates no TTY and needs no interaction, so it can be used from scripts, git hooks, editors and AI agents. Everything after -- is passed through as a list of arguments, so arguments may contain spaces (-n 'a test name'). To use shell syntax such as && or cd, wrap it explicitly:

rascal run rspec -- bash -c 'cd subproject && bundle exec rspec'

before_shell and after_shell still run around the command, but do not affect the exit status. Note that a failing before_shell command (e.g. bundle check in an environment that was never bundled) does not abort the run.

Currently requires a "bash" to exist.

rascal environments

Print the names of all available (non-hidden) environments, one per line, so that scripts can discover them without parsing an error message.

rascal clean | --all [--volumes]

Stop and remove all created containers, services, networks for either the given or all jobs.

If --volumes is given, also remove all cached volumes.

rascal update | --all

Update all images for the given job, or all jobs.

License

The gem is available as open source under the terms of the MIT License.