Installing GoCD agent on Linux

Installation of the GoCD agent using the package manager will require root access on the machine.

Install on Docker containers

To run GoCD on container please use our official docker container images

If it possible to install via rpm/deb packages as well, however this is not normally recommended as the GoCD agent packages are intended to be installed with an init system rather than managed via the container entrypoint.

Dependencies

GoCD will attempt to install a compatible Java runtime environment via recommended/weak package dependencies, which are auto-installed by default on most distributions. If you choose not to install these, you may note warnings from the package install if it cannot find a compatible Java runtime. You will then need to install your own JRE and configure GoCD to use it via the wrapper-properties.conf located within the relevant configuration directory.

If you are installing recommended dependencies, but are using an older distribution which does not contain an official package for a compatible Java runtime version, GoCD packages can also install & auto-configure themselves from freely licensed Adoptium-provided Eclipse Temurin runtimes if a repository is available. This is usually only a problem for older Debian or RHEL releases.

To use Temurin repos, see the relevant snippets for your distribution below.

RPM based distributions (e.g RHEL/AlmaLinux/RockyLinux/CentOS/Fedora)

The GoCD agent RPM installer has been tested on AlmaLinux as a proxy for RedHat Enterprise Linux. It should work on most RPM based Linux distributions.

If you prefer to use the dnf/yum repository and install via dnf/yum, paste the following in your shell -

sudo curl https://download.gocd.org/gocd.repo -o /etc/yum.repos.d/gocd.repo

Once you have the repository setup, execute

sudo dnf install -y --setopt=install_weak_deps=true go-agent

microdnf and yum will also work just fine. Alternatively, if you have the agent RPM downloaded:

sudo rpm -i go-agent-${version}.noarch.rpm

Using Adoptium Eclipse Temurin Java runtimes (optional)

To use this, before installing, upgrading or re-installing GoCD packages, add the Temurin repository (or use Adoptium’s own instructions):

# Uncomment and change the distribution name if you are not using CentOS/RHEL/Fedora, e.g for AlmaLinux/Rocky Linux
# DISTRIBUTION_NAME=rhel

sudo cat <<EOF > /etc/yum.repos.d/adoptium.repo
[Adoptium]
name=Adoptium
baseurl=https://packages.adoptium.net/artifactory/rpm/${DISTRIBUTION_NAME:-$(. /etc/os-release; echo $ID)}/\$releasever/\$basearch
enabled=1
gpgcheck=1
gpgkey=https://packages.adoptium.net/artifactory/api/gpg/key/public
EOF

# ... install GoCD package as above

Debian based distributions (e.g Ubuntu)

The GoCD agent .deb installer has been tested on LTS Ubuntu and Debian releases. However it should work on most Linux distributions which use debs.

If you prefer to use the APT repository and install via apt-get, paste the following in your shell -

sudo install -m 0755 -d /etc/apt/keyrings
curl https://download.gocd.org/GOCD-GPG-KEY.asc | sudo gpg --dearmor -o /etc/apt/keyrings/gocd.gpg
sudo chmod a+r /etc/apt/keyrings/gocd.gpg
echo "deb [signed-by=/etc/apt/keyrings/gocd.gpg] https://download.gocd.org /" | sudo tee /etc/apt/sources.list.d/gocd.list
sudo apt-get update

Once you have the repository setup, execute

sudo apt-get install --install-recommends go-agent

Alternatively, if you have the agent .deb downloaded:

sudo dpkg -i go-agent-${version}.deb

Using Adoptium Eclipse Temurin Java runtimes (optional)

To use this, before installing, upgrading or re-installing GoCD packages, add the Temurin repository (or use Adoptium’s own instructions):

sudo apt-get install -y extrepo
sudo extrepo enable temurin
sudo apt-get update

# ... install GoCD package as above

Managing the GoCD agent process

The GoCD agent script must be run with one of the following arguments:

service utilizes the service manager (e.g systemd, upstart, init.d) used by your OS.

Location of GoCD agent files

The GoCD agent installs its files in the following locations on your filesystem:

Configuring the GoCD agent

After installing the GoCD agent, you must first configure the agent with the hostname (or IP address) of your GoCD server, in order to do this:

• Open /usr/share/go-agent/wrapper-config/wrapper-properties.conf in your favourite text editor.
• Follow the instructions in the file to configure the GoCD server url
• Save the file and exit your editor.
• Run service go-agent [start|restart] to (re)start the agent.

Registering your agent with the server

For security reasons, all newly installed GoCD agents need to be enabled on the GoCD server before work is assigned to them. This prevents an unauthorized person from getting access to your source code. To enable a newly installed GoCD agent, do the following:

1. Open the GoCD server dashboard
2. Follow the instructions here to find the agent you’ve just installed on the list and add the agent to your cloud. The GoCD server will now schedule work for this agent.