Gomatic

This is a Python API for configuring ThoughtWorks GoCD.

What does it do?

If you wanted to configure a pipeline something like that shown in the GoCD documentation then you could run the following script:

#!/usr/bin/env python
from gomatic import *

configurator = GoCdConfigurator(HostRestClient("localhost:8153"))
pipeline = configurator \
    .ensure_pipeline_group("Group") \
    .ensure_replacement_of_pipeline("first_pipeline") \
    .set_git_url("http://git.url")
stage = pipeline.ensure_stage("a_stage")
job = stage.ensure_job("a_job")
job.add_task(ExecTask(['thing']))

configurator.save_updated_config()

How does it work?

Gomatic uses the same mechanism as editing the config XML through the GoCD web based UI. The GoCdConfigurator gets the current config XML from the GoCD server, re-writes it as a result of the methods called, then posts the re-written config XML back to the GoCD server when save_updated_config is called.

Gomatic doesn't use the RESTful Go API because that is (currently) far too limited for our needs.

Limitations

We wrote it for our purposes and find it very useful; however, the current version has limitations (e.g. only really supports "Custom Command" task type) and allows you to try to configure GoCD incorrectly (which GoCD will refuse to allow). We will continue to work on it and will address its current limitations.

We believe it works for the following versions (as indicated by integration_test.py):

13.1.1-16714
13.2.2-17585
13.3.1-18130
13.4.0-18334
13.4.1-18342
14.1.0-18882
14.2.0-377
14.3.0-1186
14.4.0-1356
15.1.0-1863
15.2.0-2248
16.1.0-2855
16.2.1-3027
16.3.0-3183
16.4.0-3223
16.5.0-3305
16.6.0-3590
16.7.0-3819
16.8.0-3929
16.9.0-4001
16.10.0-4131
16.11.0-4185

Install

We've written it using Python 2.7 (for the moment - should be simple to port to Python 3 - which we might do in the future). You can install it using "pip":

sudo pip install gomatic

which will install the gomatic package.

Usage

We won't document all of the options. Most of the behaviour is covered by unit tests, so look at them.

Dry run

You can see what effect Gomatic will have on the config XML by using configurator.save_updated_config(save_config_locally=True, dry_run=True). If you have kdiff3 installed, Gomatic will open it showing the diff (if there is a difference) between the config XML before and after the changes made by the GoCdConfigurator. If you don't have kdiff3 installed, use a diff tool of your choice to diff the files config-before.xml vs config-after.xml.

Reverse engineering of existing pipeline

If you have already set up a pipeline through the UI and now want to retrospectively write a script to do the equivalent, you can get Gomatic to show you the script to create an existing pipeline:

python -m gomatic.go_cd_configurator -s <GoCD server hostname> -p <pipeline name>

This mechanism can also be useful if you can't work out how to script something; you just make the change you want through the GoCD web based UI and then reverse engineer to see how to do it using Gomatic. Bear in mind that Gomatic does not currently support every configuration option available in GoCD, so it might not be possible to do everything you want to do.

Gotchas

Gomatic does not prevent you from creating config XML that GoCD will not accept. For example, if you create a stage that has no jobs, Gomatic won't complain until you try to run save_updated_config, at which time the GoCD server will reject the config XML.
Gomatic does not check that the version of GoCD it is configuring supports all the features used. For example, versions of GoCD before 15.2 do not support encrypted environment variables on stages and jobs.

Developing Gomatic

You need to install Python's virtualenv tool and create a virtual environment (once):

pip install virtualenv

Then, to create the virtual environment, either:

install autoenv and cd into the root directory of Gomatic

Or:

execute .env in the root directory of Gomatic and then execute source venv/bin/activate

Then, if you are using IntelliJ IDEA:

File -> Project Structure -> Project SDK
New -> Python SDK -> Add local
select .../gomatic/venv/bin/python

Run the tests

Unit tests:

./build.sh

Integration tests (takes a long time to download many versions of GoCD) (requires docker to be installed in order to run):

python -m unittest tests.integration_test

Contributing to Gomatic via pull request

To have the best chance of your pull request being merged, please:

Include tests for any new functionality
Separate out different changes into different pull requests
Don't delete any existing tests unless absolutely necessary
Don't change too much in one pull request

CI and releasing packages to pypi

Gomatic uses travis-ci to run the unit tests and deploy to pypi. Only tagged commits are deployed to pypi.

update value of version in setup.py
git tag -a v<version> -m 'version <version>' (e.g. git tag -a v0.3.10 -m 'version 0.3.10')
git push origin --tags

doctoryes/gomatic