@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.
GoCD requires the following software packages to build
- Git >= 2.20 (https://git-scm.com/downloads)
- 64-bit JDK 17+ (We recommend downloading it from OpenJDK, or Adoptium)
- NodeJS >= 16 (https://nodejs.org/en/download/)
- Yarn v1 package manager
npm install -g yarnwill suffice; otherwise, see https://yarnpkg.com/en/docs/install
- C/C++ build toolchain: certain
nodepackages might need to build native extensions
Homebrew is the easiest way to install the prerequisite packages
brew install git yarn openjdk nodejs
brew install git yarn asdf install # Installs JDK, NodeJS and JRuby to make interacting with Gemfiles easier
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)")
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
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
$ 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
$ find . -name target -type d ./addon-api/database/target ./agent/target ... ./tfs-impl/target ./util/target
If all went well, you should be in good shape to set up your IDE.
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.
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
After the preparation phase has succeeded, open the project in IDEA by opening the
build.gradlefile in the top level of the working directory and choosing to "Open as Project".
At this point, IntelliJ IDEA is probably prompting you if you want to import the project using gradle. Click Import Gradle Project.
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)
Open Gradle Settings
- Use the same JDK that you are using with the project.
Install the Lombok IntelliJ plugin
Lombokin the plugin settings and install it
More info here https://projectlombok.org/setup/intellij
- Restart IntelliJ IDEA after installing Lombok
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)
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:
Run -> Edit configurations...
Edit Configuration Templates...and find the
- In the VM Options box with
--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.
- Open the class
Right click and select Create 'DevelopmentServer.main()'
Configure the DevelopmentServer JVM args (
-Xmx2g) and working dir (
- Open the class
Right click and select Create 'DevelopmentAgent.main()'
Configure the DevelopmentAgent working dir
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
Ensure that your project module "server>server_test" is setup properly.
- Click "File menu > Project Structure"
- Select "Modules" in the "Project Structure" dialog
Navigate to "server>server_test" and right-click to add "JRuby" (select the right jruby version). Then right click to add "JRuby on Rails"
Configure the default RSpec run configuration
Run -> Edit configurations...
Edit configuration templates...and find the
- Check the
Use custom RSpec runner scriptcheckbox
- Set the working directory to
- Set the
Ruby SDKoption to
Use other SDK and 'rspec' gemwith the dropdown set to the correct version of JRuby that you configured above, e.g
- Open a spec file and run it
Run -> Run 'somefile_spec.rb', or
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)
Visit the following URLs:
- http://localhost:8153/go/assets/webpack/_specRunner.html (The agents, elastic profiles pages. Uses mithril 1.0). Ensure that you are running the webpack watcher.
$ ./gradlew jasmineOldServer
Open a browser and navigate to
$ ./gradlew jasmine