GoCD Developer Documentation

This documentation should allow you to setup your development environment to work on the codebase for GoCD, a free and open-source Continuous Delivery server.

Setting up your development environment

Step 1: Get the code and run a local build

Use docker image

@tomzo maintains a docker image which can be used to build and test GoCD without installing all tools on the local host. If you have a local docker daemon, consider using the image. The image uses the same tools which run on https://build.gocd.org GoCD agents, therefore it is consistent with the upstream requirement.

Manual setup

GoCD requires the following software packages to build

For Mac Users

Homebrew is the easiest way to install the prerequisite packages

brew install git yarn openjdk nodejs

For more control over versions; a generic version manager such as ASDF is a good choice. GoCD includes a .tool-versions to install precise versions.

brew install git yarn
asdf install # Installs JDK, NodeJS and JRuby to make interacting with Gemfiles easier

For Windows Users

The easiest way to get the prerequisite packages is by using Chocolatey

From an elevated command prompt run the following commands:

choco install git
choco install nodejs
choco install yarn # alternatively, npm install -g yarn
choco install vcbuildtools
choco install microsoft-build-tools

Also ensure that your JAVA_HOME environment variable is pointing to the 64-bit version (i.e. it is in "Program Files" and not "Program Files (x86)")

Clone the repository

The main repository is: https://github.com/gocd/gocd

It is highly recommended to fork the main repository and clone your fork for development. You can then add the main repository as an upstream remote:

# Assuming your github username is `developer-extraordinaire`, clone your forked repo
git clone https://github.com/developer-extraordinaire/gocd
cd gocd
# Add the main repo as the remote `upstream`
git remote add upstream https://github.com/gocd/gocd

To pull changes from upstream into your local development branches:

git fetch upstream
git merge upstream/master # alternatively, you can rebase instead

Validate that you can build the zip installers

Execute the following commands to build GoCD server and agent installers:

$ unset GEM_HOME GEM_PATH # if you're using rvm
$ ./gradlew clean agentGenericZip serverGenericZip

After a successful build, the ZIP installers for GoCD Server and GoCD Agent are outputted to installers/target/distributions/zip/

$ ls installers/target/distributions/zip/
go-agent-16.7.0-3795.zip  go-server-16.7.0-3795.zip

Compiled bytecode and other build artifacts can be found in each module's target/ subdirectory:

$ find . -name target -type d

If all went well, you should be in good shape to set up your IDE.

Step 2: Setup IntelliJ

The core team use IntelliJ IDEA as the IDE for GoCD development (at least for Java code and related derivatives). If you use another IDE, it will be up to you to figure out a working configuration based off of these instructions. Either the the Community Edition or the paid Ultimate edition will work.

For TypeScript, JavaScript, Sass, Ruby, and other parts, some of us use other editors, such as Visual Studio Code, Sublime Text, Vim, Emacs, etc. That is completely optional.

  1. Prior to importing a GoCD project in IntelliJ IDEA, one needs to build some prerequisite code to prepare one's working directory. This is done with the following command -- it may take a few minutes to run the first time, so maybe go grab a coffee :)

     $ ./gradlew clean prepare
  2. After the preparation phase has succeeded, open the project in IDEA by opening the build.gradle file in the top level of the working directory and choosing to "Open as Project".

  3. At this point, IntelliJ IDEA is probably prompting you if you want to import the project using gradle. Click Import Gradle Project.

  4. Open project settings.

    • Select the latest JDK that is installed

    • OPTIONAL for IDEA Ultimate Edition: Setup a JRuby SDK (use $GOCD_HOME/server/scripts/jruby) as the JRuby binary (Ruby support is only available to Ultimate Edition users)

  5. Open Gradle Settings

    • Use the same JDK that you are using with the project.

  6. Install the Lombok IntelliJ plugin

  7. Configure annotation processing

    • The Lombok plugin will prompt you to setup an annotation processor
    • Enable annotation processing, setting IDEA to obtain processors from the project classpath (the default setting)

  8. Configure a default JUnit template

    • For Java 16+ compatibility, GoCD server requires certain JDK packages to have internals opened for access due to the way it was originally designed. The Gradle configurations will do this automatically when running tests against the server, however if you choose to run test tests using IntelliJ IDEA itself, you will find tests failing with accessibility errors. To make each JUnit configuration start with the required access you can edit the default template:
    • Open Run -> Edit configurations...
    • Click Edit Configuration Templates... and find the JUnit default configuration
    • In the VM Options box with -ea, add --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED. For the most up-to-date list of required opens, refer to the JvmModuleOpensArgs within the server Gradle config here.
    • After this, each JUnit run configuration that is manually or dynamically created should have the necessary configuration to work without issue.

2.1: Running the Development Server via IntelliJ IDEA

  • Open the class DevelopmentServer
  • Right click and select Create 'DevelopmentServer.main()'

  • Configure the DevelopmentServer JVM args (-Xmx2g) and working dir (server)

2.2: Running Development Agent via IntelliJ IDEA

  • Open the class DevelopmentAgent
  • Right click and select Create 'DevelopmentAgent.main()'

  • Configure the DevelopmentAgent working dir agent

2.3: Running RSpec tests from the command line

Here are some RSpec specific commands you may find useful —

$ ./gradlew rspec # run all specs, with default arguments
$ ./gradlew rspec -Popts='--pattern spec/**/api_v**/*_spec.rb' # to run api specs
$ ./gradlew rspec -Popts='--pattern spec/controllers' # to run controller specs
$ ./gradlew rspec -Popts='--pattern spec/foo/bar_spec.rb' # to run a single spec

It's probably quicker to run the RSpec tests from the command line instead of gradle:

cd server/webapp/WEB-INF/rails
../../../scripts/jruby -S rspec
../../../scripts/jruby -S rspec --pattern 'spec/**/api_v**/*_spec.rb' # to run api specs
../../../scripts/jruby -S rspec --pattern spec/controllers # to run controller specs
../../../scripts/jruby -S rspec --pattern spec/foo/bar_spec.rb # to run a single spec

2.3b: [OPTIONAL for Ultimate Edition] Running RSpec tests from IntelliJ IDEA Ultimate Edition

  1. Ensure that your project module "server>server_test" is setup properly.

    1. Click "File menu > Project Structure"
    2. Select "Modules" in the "Project Structure" dialog
    3. Navigate to "server>server_test" and right-click to add "JRuby" (select the right jruby version). Then right click to add "JRuby on Rails"

  2. Configure the default RSpec run configuration

    1. Open Run -> Edit configurations...
    2. Click Edit configuration templates... and find the RSpec default configuration
    3. Check the Use custom RSpec runner script checkbox
    4. Select rspec from <project-directory>/server/scripts/jruby/rspec
    5. Set the working directory to <project-directory>/server/webapp/WEB-INF/rails
    6. Set the Ruby SDK option to Use other SDK and 'rspec' gem with the dropdown set to the correct version of JRuby that you configured above, e.g jruby-
    7. Click Apply to save
    8. Open a spec file and run it Run -> Run 'somefile_spec.rb', or Ctrl+Shift+F10

2.4: Working on single page apps

If you're working on some of the new pages in GoCD (pipeline config, agents, elastic profiles...), this will watch your filesystem for any JS changes you make and keep compiling the JS in the background. This usually takes a couple of seconds to compile, after you hit save.

# forking in a subshell won't change the directory after interrupting/exiting
$ (cd server/src/main/webapp/WEB-INF/rails && yarn run webpack-watch)

2.5: Running Javascript tests

To run javascript tests —

In development environment (very quick)

Visit the following URLs:

In order to run old javascript specs through browser, run following command to start server -

$ ./gradlew jasmineOldServer

Open a browser and navigate to http://localhost:8888/

In CI environment (very slow for running tests after every change)

$ ./gradlew jasmine

results matching ""

    No results matching ""