gocd / docs.go.cd

GoCD user documentation

Documentation for GoCD - Continuous Delivery server

This repository contains the source code for the user documentation for GoCD. The documentation is available at https://docs.gocd.org/current/.

Contributing

We encourage you to contribute to GoCD. For information on contributing to GoCD, please see our contributor's guide. A lot of useful information like links to user documentation, design documentation, mailing lists etc. can be found in the resources section.

To make changes to GoCD's documentation, you can do this:

1. Install all dependencies

   The dependencies for building the documentation are:

   • nodejs (known to work with v18)
   • Ruby (known to work with 3.2)

   Then run this to get all the dependent gems:

   bundle

2. To install npm dependencies

   npm install

3. Run the documentation on the local server (defaults to http://localhost:1313)

   npm run index
   npm run serve

Publishing to GitHub pages

The contents of the public directory needs to be pushed out to the gh-pages branch of the repository.

bundle exec rake publish

Check the latest changes deployed here.

To build search index

npm run index

To run hugo with different arguments

npm run hugo [arguments]

License

Copyright 2022 Thoughtworks, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

docs.go.cd's Issues

Pipelines as code example does not save

The Pipelines as code section has this example code (and a similar block for JSON) which does not save on GoCD 17.8.0:

<config-repos>
    <config-repo plugin="yaml.config.plugin">
        <git url="https://github.com/tomzo/gocd-yaml-config-example.git" />
    </config-repo>
</config-repos>

Error:

I updated the element to <config-repo plugin="yaml.config.plugin" id="myreponame"> and it worked, but it'd be great if this was present in the docs. Happy to submit a PR for this, but is there a preferred value for the id? Or just any unique string?

Getting error while installing using APT repository.

Hello,
I'm trying to install GoCD on Ubuntu using the APT repository following the instructions here
However, I'm getting the following error

sudo apt-get update
deb [signed-by=/etc/apt/keyrings/gocd.gpg] https://download.gocd.org /
Hit:1 https://dl.google.com/linux/chrome/deb stable InRelease
Get:2 https://download.gocd.org  InRelease [2478 B]                                                                   
Err:2 https://download.gocd.org  InRelease                                                                            
  The following signatures couldn't be verified because the public key is not available: NO_PUBKEY D8843F288816C449
Hit:3 http://security.ubuntu.com/ubuntu jammy-security InRelease
Hit:4 http://in.archive.ubuntu.com/ubuntu jammy InRelease
Hit:5 http://in.archive.ubuntu.com/ubuntu jammy-updates InRelease
Hit:6 http://in.archive.ubuntu.com/ubuntu jammy-backports InRelease
Reading package lists... Done
W: GPG error: https://download.gocd.org  InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY D8843F288816C449
E: The repository 'https://download.gocd.org  InRelease' is not signed.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
N: See apt-secure(8) manpage for repository creation and user configuration details.

Link checker seems to not work?

See #286. I'd have expected our link checker task to ensure this should not have happened.

app-deployment in kubernetes getting started fails but reports success

As stated in topic. Following the getting started doc, the deployment at the end fails, but the script doesn't catch the failure.

minikube version: v0.25.0
Darwin KM-MBP-15.local 17.4.0 Darwin Kernel Version 17.4.0: Sun Dec 17 09:19:54 PST 2017; root:xnu-4570.41.2~1/RELEASE_X86_64 x86_64
kubectl version
Client Version: version.Info{Major:"1", Minor:"9", GitVersion:"v1.9.2", GitCommit:"5fa2db2bd46ac79e5e00a4e6ed24191080aa463b", GitTreeState:"clean", BuildDate:"2018-01-18T10:09:24Z", GoVersion:"go1.9.2", Compiler:"gc", Platform:"darwin/amd64"}
Server Version: version.Info{Major:"1", Minor:"9", GitVersion:"v1.9.0", GitCommit:"925c127ec6b946659ad0fd596fa959be43f0cc05", GitTreeState:"clean", BuildDate:"2017-12-15T20:55:30Z", GoVersion:"go1.9.2", Compiler:"gc", Platform:"linux/amd64"}

[go] Task: ./app-deployment.shtook: 0.450s

Namespace gocd

Creating deployment
{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {

  },
  "status": "Failure",
  "message": "the API version in the data (apps/v1beta2) does not match the expected API version (apps/v1)",
  "reason": "BadRequest",
  "code": 400
}

Update User Management screenshots before 19.2.0 release

Update the screenshots here and other relevant places for User Management a.k.a User summary page

Consolidate docs for all supported versions into master

Problems with maintaining multiple branches:

• Backporting changes is comparatively harder
• There is no staging area to test all versions simultaneously
• Potentially different versions of gitbook are present in different branches, some of which are outdated and hard to maintain
• Different pipelines are needed to test/deploy each version

Proposed change:
Maintain directories for different versions in master itself, using the same gitbook version. Build scripts and pipelines would need to be changed accordingly.

Thoughts, suggestions, comments are welcome.

Add a note about upgrading addons jar while upgrading the GoCD server

The upgrade documentation here should have an explicit note of upgrading addons with the corresponding GoCD server version.

Agent configuration documentation, what does it mean?

It says:

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

The file has:

# setup the GoCD server URL
wrapper.app.parameter.100=-serverUrl
wrapper.app.parameter.101=http://localhost:8153/go

What is 100, 101? I think maybe it should be:

wrapper.app.parameter.101=http://gocd.localinternaldomain.com:8153/go

But this is only a guess. Maybe it is clear if you already know some java specific configuration syntax?

Alias pages don't work in Firefox

See: https://docs.gocd.org/current/faq/environment_variables.html

Works in Chrome.

Implement search functionality for docs website

Upgrading go page has an incomplete sentence

"While upgrading GoCD agents is not necessary (agents will usually auto-upgrade if they detect a new version deployed on the server). Going forward, we will ensure that agents are backward compatible with atleast 1"

Probably you want to finish the sentence :)

Add Documentation for Infrastructure as Code

Currently the only documentation about any kind of configuration uses the UI. I have not found any example where this was not the case.

Ideally I would wish for examples in terraform, but it would also be enough to know where the configuration is placed and what the format and schema of the file is. If this was treated a stable API, it would be even better.

Insecure storage of passwords

Add warning to indicate the password storage in password file is not secured compared to other authentication method

Include documentation around adding a private Github repo to Go

This is a placeholder for the documentation update to add notes on how to add private Github repositories to Go in the FAQ section.

Go agent 19.4 with openjdk 12 issue

Hi,

I installed a new agent on a server with the latest version available (19.4.0 Windows).
Installation was ok, but I did not achieve to see the new agent on my GoCD Server (19.1 Windows).
After some investigation, I saw this error in "go-agent-stderr" log file :

2019-06-04 11:26:36,658 - [Tue Jun 04 11:26:36 CEST 2019] Starting process:
2019-06-04 11:26:36,658 - [Tue Jun 04 11:26:36 CEST 2019] Working directory : D:\Program Files (x86)\Go Agent
2019-06-04 11:26:36,658 - [Tue Jun 04 11:26:36 CEST 2019] Application arguments: [-serverUrl, https://172.XXX.XXX.XX:8154/go, -sslVerificationMode, NONE]
2019-06-04 11:26:36,658 - [Tue Jun 04 11:26:36 CEST 2019] GoCD Version: 19.1.0-8469
2019-06-04 11:26:37,627 - Running GoCD requires Java version >= VERSION_1_8 and <= 11. You are currently running with Java version 12. GoCD will now exit!

I could see the openjdk version packaged with the agent is 12.0X. I checked on my previous installation agent 19.2, i got a openjdk version 11.
Either the agent source code is incorrect and it should let the use of java 12, or the jdk packaged should be changed to java 11.

docker run -it -v /var/run/docker.sock:/var/run/docker.sock -e GO_SERVER_URL="https://<go-server-ip>:8154/go" <gocd-agent-image-with-docker> where to find gocd-agent-image-with-docker?

https://docs.gocd.org/current/gocd_on_kubernetes/docker_workflows.html in this page it is mentioned that.

Documentation for configuring agent server bind port for Agent Health Check AP

Summary

Documentation required for specifying agent server bind port ( defaults to 8152 ) but is configurable and this needs to be documented.

Basic environment details

Go Version: 17.11.0
JAVA Version: JAVA8
OS: NA
Browser vendor and version (if relevant):NA

Steps to Reproduce

1. Register multiple agents from the same machine
2. Use agent health check API to check for agent health
3. Bring down the first registered agent
4. Check for second agent health

Expected Results

User should have the information about the configurable port

Actual Results

Currently, the documentation is missing

Provide a link icon for subsections

The old docs.go.cd used to show a link icon for each subsection on hover. Clicking on this would provide the provide the link to the subsection in the url. It would be nice to have that for the new docs.

"config" repos vs. material repos

As a newcomer to GoCD, acting in a sysadmin/operations role, I was reading about how it implements its pipeline configuration from code. The official documentation kept showing, but not explaining why, a separate "configs only" git repository was being used for the "config" repo (that is, separate from the "material" repo). I was nearly completely turned off on GoCD by the usage of separate "config" repos appearing to be a hard requirement, as no other option was pointed out as possible.

The following enormous closed Github issue is the first place I ever saw it mentioned that using the material repository as the "config" repo was possible (or at least it is part of the detailed proposal..): gocd/gocd#1133

I think the documentation would benefit from spelling this out more clearly, perhaps indicating what the pros and cons of "config repo" vs. "config in material repo" are.

I'm not qualified on the topic for a PR submission.

Wrong documentation found in proxy section

Hey guys

on this page https://docs.gocd.org/current/installation/configure-agent-proxy.html are 2 typos.

the proxy port

wrapper.java.additional.101-Dhttps.proxyPort=3128 ## WRONG
wrapper.java.additional.101=-Dhttps.proxyPort=3128 ## RIGHT

do not proxy connections to these hosts

wrapper.java.additional.102-Dhttp.nonProxyHosts=localhost|.department.acme.com ## WRONG
wrapper.java.additional.102=-Dhttp.nonProxyHosts=localhost|.department.acme.com ## RIGHT

Invest 30 minutes of debug to find the issue there /o.

Maybe it's possible to fix it :)

Greets
Andreas

Document all the system properties that a user can configure

Currently we document only 4 system properties for the user to configure - https://docs.gocd.org/current/advanced_usage/other_config_options.html

Mac agent logs incorrectly documented

Moved over from: gocd/gocd#2033

File which needs to be changed: https://github.com/gocd/docs.go.cd/blob/master/installation/install/agent/osx.md

Content (from gocd/gocd#2033, by @janfabry):

Issue Type

• Documentation Report

Summary

The Go Agent docs for Mac OS X mention logs in /var/log/system.log, but useful logs are actually sent somewhere to the ~/Library/Application Support/Go Agent/*.log files.

Environment

Running the Go agent and trying to debug connection problems.

Basic environment details

Go Version: 16.2.1.3027
JAVA Version: 1.8.0_40
OS: Max OS X 11.1

Steps to Reproduce

Start the Go agent, check /var/log/system.log for output.

Expected Results

Some output from the agent.

Actual Results

No output :-)

Useful logs are located in ~/Library/Application Support/Go Agent in the following files:

• osx-app.log: the main log file of the app
• go-agent-bootstrapper.log
• go-agent-launcher.log

I would certainly mention the osx-app.log file in the documentation.

Installing multiple agent. There is no doc folder in the area specified

I am running a go-agent. I want to run multiple agents from the same machine. Earlier I remember there was a documentation on how to do this on the main site. Now as per this file

docs.go.cd/content/advanced_usage/admin_install_multiple_agents.md

It is advised to look in /usr/share/go-agent/docs.

On my installation there is no docs folder. How do I find this?

Improve navigation between pages

See the new page:

https://docs.gocd.org/current/gocd_on_kubernetes.html

vs. the old page:

https://docs.gocd.org/19.1.0/gocd_on_kubernetes.html

At least, the old page has a link to go to the next page. The new page just drops you into a nearly empty page.

Document how to downgrade the GoCD server.

gocd on kubernetes plugin reinstall

The plugin will be re-downloaded whenever the goserver pod is restarted,
Can't add a test in install script? When the plugin exists, it will not be downloaded again

Linux configuration does not match the documentation?

Issue Type

• Bug Report
• Documentation Report

Summary

I followed the web instructions to download and install server and agent 21.2.0 on Linux. It seems to work fine. I'd like to make some global configuration adjustments to the jobs that are run. The docs suggest that configuration can be done in /etc/default/go-agent. In fact, https://cvjt.gitbooks.io/gocd-official-manual/content/installation/install/agent/linux.html suggests that I should configure GO_SERVER_URL in there.

But it doesn't exist.

Environment

Up-to-date Ubuntu Linux 21.04.

GO_DEPENDENCY_LABEL_${pipeline name} environment variable description is incorrect

It's not clear in the docs that the GO_DEPENDENCY_LABEL_ suffix should be the upstream pipeline's "Material Name". This name should be converted to uppercase with hyphens converted to underscores.

Eg:
The Pipeline Label for an Upstream Pipeline with "Material Name" = "upstream_services-frontend"

Would be available as the environment variable:
${GO_DEPENDENCY_LABEL_UPSTREAM_SERVICES_FRONTEND}

Some Pages Not Responsive

Some GoCD documentation pages aren't responsive to browser widths between about 686px and 1430px. For example, this page about installing an agent on Linux is cut off on the right and there isn't a horizontal scrollbar - Chrome on Windows 10:

https://docs.gocd.org/current/installation/install/agent/linux.html

tutorial doc points to incorrect image

Issue Type

• Documentation Report

Summary

The pod config in the tutorial https://docs.gocd.org/current/gocd_on_kubernetes/importing_a_sample_workflow.html
references an image gocddemo/gocd-agent-dind:webinar which uses GoCD Version: 18.3.0-6540

kind: Pod
metadata:
  name: pod-name-prefix-{{ POD_POSTFIX }}
  labels:
    app: web
spec:
  containers:
    - name: gocd-agent-container-{{ CONTAINER_POSTFIX }}
      image: gocddemo/gocd-agent-dind:webinar
...

v18.3.0-6540 has the https serverUrl requirement which causes the helm deployed gocd app to fail

bash-4.4# java -jar agent-bootstrapper.jar -help
[Wed May 05 02:35:20 GMT 2021] Starting process:
[Wed May 05 02:35:20 GMT 2021]   Working directory    : /go-agent
[Wed May 05 02:35:20 GMT 2021]   Application arguments: [-help]
[Wed May 05 02:35:20 GMT 2021]            GoCD Version: 18.3.0-6540
...
  Options:
    -help
      Print this help
    -rootCertFile
      The root certificate from the certificate chain of the GoCD server (in
      PEM format)
  * -serverUrl
      The GoCD server URL. Must begin with `https://`, and end with `/go`
    -sslVerificationMode
      The SSL verification mode.
      Default: NONE
      Possible Values: [FULL, NONE, NO_VERIFY_HOST]

Latest version does not have that requirement v21.2.0

bash-5.1$ /gocd-jre/bin/java -jar agent-bootstrapper.jar -help
[Wed May 05 02:36:20 GMT 2021] Starting process:
[Wed May 05 02:36:20 GMT 2021]   Working directory    : /go-agent/lib
[Wed May 05 02:36:20 GMT 2021]   Application arguments: [-help]
[Wed May 05 02:36:20 GMT 2021]            GoCD Version: 21.2.0-12498
[Wed May 05 02:36:20 GMT 2021]            Java Version: 15.0.2
[Wed May 05 02:36:20 GMT 2021]        Operating System: Linux(5.10.25-linuxkit)
Usage: java -jar agent-bootstrapper.jar [options]
  Options:
    -help
      Print this help
    -rootCertFile
      The root certificate from the certificate chain of the GoCD server (in
      PEM format)
  * -serverUrl
      The GoCD server URL. Example: http://gocd.example.com:8153/go
    -sslCertificateFile
      The X509 certificate for mutual TLS.
    -sslPrivateKeyFile
      The private key for mutual TLS.
    -sslPrivateKeyPassphraseFile
      The file containing the passphrase for decoding the SSL private key.
    -sslVerificationMode
      The SSL verification mode.
      Default: FULL
      Possible Values: [FULL, NONE, NO_VERIFY_HOST]

Environment

Docker Desktop for Mac

Steps to Reproduce

• Follow the instructions in https://docs.gocd.org/current/gocd_on_kubernetes using helm steps verbatim

Expected Results

Hello world example should work

Actual Results

Hello world example didn't work.

Possible Fix

Update docs to point to more recent agent pod template. Maybe gocd/gocd-agent-docker-dind:v21.2.0?

Set up redirects to internal pages.

Some of the pages are duplicated in the repository. This is to support backward compatibility of few links.

Examples:

• https://docs.gocd.org/current/faq/environment_variables.html
  https://docs.gocd.org/current/faq/dev_use_current_revision_in_build.html
• https://docs.gocd.org/current/installation/troubleshooting.html
  https://docs.gocd.org/current/installation/troubleshoot_installer.html

Broken link

Link to GoCD Server installation instructions from https://docs.gocd.org/current/installation/ is incorrect and leaves 404 error.

404 Not Found
Code: NoSuchKey
Message: The specified key does not exist.
Key: current/installation/installation/installing_go_server.html
RequestId: 97C3C9BE24A91554
HostId: jtNesGtHcxODA+YzdX5DX+qsnM7oV0ghKNFTm571/a1heQucPikGbHzsoIKGL4TLRJMAh7gPgK8=

Documentation mentions cruise-config.xml, but doesn't specify its location

I'm reading through the documentation of GoCD installation on Linux: https://docs.gocd.org/current/installation/install/server/linux.html#copying-existing-config-to-a-new-gocd-server-instance

It nicely enumerates a set of configuration files, which does not include cruise-config.xml: https://docs.gocd.org/current/installation/install/server/linux.html#location-of-gocd-server-files.

Then in the next paragraph, cruise-config.xml suddenly comes up out of nowhere, and it's never mentioned, where it is located: https://docs.gocd.org/current/installation/install/server/linux.html#copying-existing-config-to-a-new-gocd-server-instance.

Please, improve your (otherwise very beautiful and user-friendly) documentation.

Thank you!

Add documentation for use of the webhooks for triggering materials

There appears to be no consolidated guide/howto for use of the SCM notification webhooks. While they are included in the API docs these aren't really traditional API and seem they should be documented in the main documentation.

Suggested content

• at least with links to the API docs to avoid repeating ourselves
• explain why you might want to use this (it's often a suggestions to alleviate polling load/throttling on target VCS systems and take load off the material subsystem threads (and even H2) so it'd be nice to have something to point to
• link from Configuration / Add Material perhaps?
• As suggested at gocd/gocd#10091 (comment) perhaps it should also note how to disable polling on materials.
• the config_repos webhooks added in 21.1.0 in #8023 seem to not be documented at all; this documentation should probably include mention of that, or build on top of gocd/api.go.cd#1037

Document for new git material shallow clone option

We need add some new user document for a new git material option. (gocd/gocd#1997).

@juhijariwala, I over heard you are splitting two document repos, and wondering is this a good send PR for this repo?

-- wpc

Doc page using image with obsolete/removed feature

https://docs.gocd.org/current/configuration/managing_dependencies.html

sidebar feels jumpy when expanding a sidebar section

When expanding a sidebar section, other sidebar sections are forced to collapse, this causes your mouse to hover on a link it was not hovering on before. I was taken aback and almost got confused if I did something wrong when I noticed this behavior.

Update pipelines as code page

https://docs.gocd.org/current/advanced_usage/pipelines_as_code.html

Minor Improvement to https://docs.gocd.org/22.1.0/configuration/dev_authentication.html

I found the instructions slightly confusing as the example shows a relative path.

Please indicate

1. Where the relative paths starts from,
2. That a fully qualified path may be used.

Improve "Other config options" page

I have just spent hours to figure out how to change the go-server's port. (Environment: Linux)

The official doc here does not provide enough information.

Workaround:

Adding wrapper.java.additional.{} property to /usr/share/go-server/wrapper-config/wrapper.conf

For example,

wrapper.java.additional.12=-Dcruise.server.port=28153

Add a detailed document about hardware specifications

minikube instructions start minikube twice

In https://docs.gocd.org/18.3.0/gocd_on_kubernetes/gocd_helm_chart/configure_cluster.html#configure-service-account instructions are given for starting the cluster with kubeadm. If following the getting started from the beginning the cluster has already been started at https://docs.gocd.org/18.3.0/gocd_on_kubernetes/gocd_helm_chart/setup.html#2-setup-a-kubernetes-cluster

Documentation links with fragments do not scroll in Chrome

Browser: Google Chrome Version 76.0.3809.100 (Official Build) (64-bit)
OS: MacOS 10.14.6

Steps to reproduce:
Open a link to the documentation containing a fragment, such as this in Chrome

Expected: The page should scroll to Step 2: Material

Actual: The page doesn't scroll to the right section, stays on top of the page

(Works as expected on Firefox)

Beta feature: Upload plugins property is incorrect

The following page shows that **GO_SERVER_SYSTEM_PROPERTIES**should be set to -Dgo.plugin.upload.enabled=true. This does not seem to work for me, but @varshavaradarajan provided the following value which does work: -Dgo.plugin.upload.enabled=Y (thread). I'm using a gocd docker container and it might differ a bit from a standard install, but I doubt it.

This page https://github.com/gocd/docs.go.cd/blob/master/beta/plugin_upload.md should be updated to reflect the correct property value.

Update documentation to correct the information about TFS sdk and supported versions

https://docs.gocd.org/current/configuration/tfs_config.html is outdated

Some of the outdated info that I could find:

• Go server and agent uses TFS Java SDK v10
• TFS 2011 support has not been verified.

Add a note about the env vars that go sets by default.

Add a note about environment variables such as GO_REVISION, GO_DEPENDENCY_LABEL etc that go sets by default, which could be used in the tasks.

Update screenshots

The following pages/SPA have been modified but the screenshots used in the doc still shows the older ones. They should be updated.

• Pipeline Groups SPA
• Template SPA
• Environments SPA
• User Management ( related issue: #234 )
• Server Config SPA
• Pipeline History/Activity SPA

Docs site design when GDPR banner is shown

When the GDPR banner regarding cookies is visible, the design of the page changes.
Banner visible:

Banner invisible:

Using an environment variable as the value to set another environment variable.

On a job level environment variable configuration:

The following works when using parameters passed from another pipleline to my template:
Environment Variables
Name Value
BRANCH #{PIPELINE_BRANCH}_INDEX

However, this does not.
Name Value
BRANCH ${STAGE_LEVEL_ENVIRONMENT_VARIABLE}_INDEX

in the latter case, it takes the literal value without replacing with the environment variable