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.
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.
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
We don't support the below versions anymore, however we did at some point in time, so it might still work in newer versions:
- 16.3.0-3183 [unsupported from 0.6.8 onwards]
- 16.4.0-3223 [unsupported from 0.6.8 onwards]
- 16.5.0-3305 [unsupported from 0.6.8 onwards]
- 16.6.0-3590 [unsupported from 0.6.8 onwards]
We've written it using Python 2.7 but have been working on supporting python 3.5 and use
tox to ensure that all unit tests are passing for both 2.7 and 3.5. You can install gomatic it using "pip":
sudo pip install gomatic
which will install the gomatic package.
We won't document all of the options. Most of the behaviour is covered by unit tests, so look at them.
You can see what effect Gomatic will have on the config XML by using
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
If you don't have
kdiff3 installed, use a diff tool of your choice to diff the files
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.
- 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.
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
cdinto the root directory of Gomatic
.envin the root directory of Gomatic and then execute
Then, if you are using IntelliJ IDEA:
- File -> Project Structure -> Project SDK
- New -> Python SDK -> Add local
Run the tests
pip install -r requirements.txt
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
- update value of
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
git push origin --tags