https://github.com/tomzo/gocd-yaml-config-plugin

Plugin to declare GoCD pipelines and environments configuration in YAML
https://github.com/tomzo/gocd-yaml-config-plugin

gocd pipelines-as-code

Last synced: 4 months ago
JSON representation

Plugin to declare GoCD pipelines and environments configuration in YAML

Host: GitHub
URL: https://github.com/tomzo/gocd-yaml-config-plugin
Owner: tomzo
License: apache-2.0
Created: 2016-07-13T17:38:01.000Z (almost 10 years ago)
Default Branch: master
Last Pushed: 2026-02-01T15:48:00.000Z (5 months ago)
Last Synced: 2026-02-01T16:18:29.541Z (5 months ago)
Topics: gocd, pipelines-as-code
Language: Java
Homepage:
Size: 1.21 MB
Stars: 212
Watchers: 12
Forks: 95
Open Issues: 10
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

[![Google Groups](https://img.shields.io/badge/Google_Groups-user_help-purple)](https://groups.google.com/g/go-cd)
[![GitHub Discussions](https://img.shields.io/badge/GitHub_discussions-user_&_dev_chat-green)](https://github.com/gocd/gocd/discussions)

# gocd-yaml-config-plugin

[GoCD](https://www.gocd.org) plugin to keep **pipelines** and **environments**
configuration in source-control in [YAML](http://www.yaml.org/).
See [this document](https://docs.gocd.org/current/advanced_usage/pipelines_as_code.html)
to find out what are GoCD configuration repositories.

This is the second GoCD configuration plugin, which enhances some of shortcomings of
[JSON configuration plugin](https://github.com/tomzo/gocd-json-config-plugin)

* Format is **concise**. Unlike JSON, there are no unnecessary quotations `"`, brackets `{}` and commas `,`
* Tries to **enforce correctness** where possible. By using maps instead of lists and shorter object graphs.
* Allows to have multiple pipelines and environments in single file. But doesn't force it.
* **Comments in configuration files** - YAML supports comments,
so you can explain why pipeline/environment it is configured like this.

# Table of contents

1. [Setup](#setup)
1. [Example configuration](#example)
1. [File pattern](#file-pattern)
1. [Validation](#Validation)
1. **[Format reference](#Format-reference)**
1. [Format version](#Format-version)
1. [Issues and questions](#Issues-and-questions)
1. [Development](#Development)
1. [License](#License)

# Setup

**Step 1**: GoCD versions newer than `17.8.0` already have the plugin bundled. You don't need to install anything.

If you're using GoCD version *older than 17.8.0*, you need to install the plugin in the GoCD server. Download it from
[the releases page](https://github.com/tomzo/gocd-yaml-config-plugin/releases) and place it on the GoCD server in
`plugins/external` [directory](https://docs.gocd.org/current/extension_points/plugin_user_guide.html).

**Step 2**: Follow [the GoCD documentation](https://docs.gocd.org/current/advanced_usage/pipelines_as_code.html#storing-pipeline-configuration-in-json) to add a new configuration repository.

You can use the example repository at: `https://github.com/tomzo/gocd-yaml-config-example.git`.

In your config repo (`tomzo/gocd-yaml-config-example.git` in this case), ensure that your GoCD yaml config is suffixed with `.gocd.yaml`. Any file ending in `.gocd.yaml` is picked up by the plugin. Give it a minute or so for the polling to happen. Once that happens, you should see your pipeline(s) on your dashboard.

## Example

More examples are in [test resources](src/test/resources/examples/).

```yaml
#ci.gocd.yaml
format_version: 9
environments:
testing:
environment_variables:
DEPLOYMENT: testing
secure_variables:
ENV_PASSWORD: "s&Du#@$xsSa"
pipelines:
- example-deploy-testing
- build-testing
pipelines:
mypipe1: # definition of mypipe1 pipeline
group: mygroup # note that the group name can contain only of alphanumeric & underscore characters
display_order: 10
label_template: "${mygit[:8]}"
lock_behavior: none
parameters: # list of parameters that can be configured for a pipeline
param1: value1
materials:
mygit: # this is the name of material, the name can contain only of alphanumeric & underscore characters
# keyword git says about type of material and url at once
git: https://my.example.org/mygit.git
branch: ci
myupstream: # this name does not matter, but there should be no 2 materials with the same name
# type is optional here, material type is implied based on presence of pipeline and stage fields
# type: dependency
pipeline: pipe2
stage: test
stages: # list of stages in order
- build: # name of stage
clean_workspace: true
jobs:
csharp: # name of the job
resources:
- net45
artifacts:
- build:
source: bin/
destination: build
- test:
source: tests/
destination: test-reports/
- test:
source: coverage.xml
tabs:
report: test-reports/index.html
tasks: # ordered list of tasks to execute in job csharp
- fetch:
pipeline: pipe2
stage: build
job: test
source: test-bin/
destination: bin/
- exec: # indicates type of task
command: make
arguments:
- "VERBOSE=true"
# shorthand for script-executor plugin
- script: ./build.sh ci
```

## File pattern

The default pattern is `**/*.gocd.yaml,**/*.gocd.yml`, which will recursively search the entire repository for all files ending with `.gocd.yaml` or `.gocd.yml`.

You can set a custom file pattern per configuration repository using the GoCD configuration UI:
![yaml pattern config](yaml_file_pattern.png)

Or in the config XML using ``:

```xml

file_pattern

pipelines/build/*.yml,pipelines/lint/*.yml

```

# Validation

You can validate if proposed GoCD YAML changes will be accepted by the server. Currently, 2 options are available:
* Use a [GoCD mergable github action](https://github.com/GaneshSPatil/gocd-mergeable)
* [Validate from your local machine](#validation-using-cli)

## Validation using CLI

*You may find this [introductory blog post useful](https://kudulab.io/posts/gocd-preflight-validation/).*

There is an ongoing effort to allow in-depth validation of configuration **before pushing configuration to the source control**. This is provided by [GoCD's preflight API](https://api.gocd.org/current/#preflight-check-of-config-repo-configurations) and [gocd-cli](https://github.com/gocd-contrib/gocd-cli).

You have several options to configure validation tools on your workstation:
* If you have a local docker daemon, use the [gocd-cli-dojo](https://github.com/gocd-contrib/docker-gocd-cli-dojo) image. Follow the [setup instructions](https://github.com/gocd-contrib/docker-gocd-cli-dojo#setup) in the image readme.
* If you don't want to use docker, you'll need to [setup `gocd-cli` on your host](https://github.com/gocd-contrib/gocd-cli).

Either way you'll have `gocd` binary in your `PATH` or inside the docker container.

### Syntax validation

This will check general validity of the yaml file, without talking to the GoCD server:
```bash
gocd configrepo syntax --yaml pipeline.gocd.yaml
```

### Preflight validation

This command will parse and submit your yaml file to the configured GoCD server.
```
gocd configrepo preflight --yaml -r dotnet-dojo pipeline.gocd.yaml
```
Where `-r` is the configuration repository id, which you have earlier configured on GoCD server. You can check it on config repos page of your GoCD server, at `/go/admin/config_repos`. It is in the upper left corner of each config repo.
![config repo id](config_repo_id.png)

For new repositories, when you haven't added config repo to the server yet, you can also check if it is correct, just skip the `-r` argument.
```
gocd configrepo preflight --yaml pipeline.gocd.yaml
```

# Format reference

See [official GoCD XML configuration reference](https://docs.gocd.org/current/configuration/configuration_reference.html)
for details about each element. Below is a reference of format supported by this plugin.
Feel free to improve it!

1. [**Format version**](#format-version)
1. [Environment](#environment)
1. [Environment variables](#environment-variables)
1. [Parameters](#parameters)
1. [Pipeline](#pipeline)
* [Tabs](#tabs)
* [Controlling the display order](#display-order-of-pipelines)
* [Tracking tool](#tracking-tool)
* [Timer](#timer)
* [Locking](#pipeline-locking)
1. [Stage](#stage)
* [Approval](#approval)
1. [Job](#job)
* [Property](#property)
* [Tab](#tab)
* [Many instances](#run-many-instances)
1. [Tasks](#tasks)
* [rake](#rake)
* [ant](#ant)
* [nant](#nant)
* [exec](#exec)
* [fetch](#fetch)
* [pluggabletask](#plugin)
* [script](#script)
1. [Materials](#materials)
* [dependency](#dependency)
* [package](#package)
* [git](#git)
* [svn](#svn)
* [perforce](#perforce)
* [tfs](#tfs)
* [hg](#hg)
* [pluggable scm](#pluggable)
* [config repo](#configrepo)
1. [Secure variables](#to-generate-an-encrypted-value)
1. [Retrieving secrets from Secrets Management plugins in values](#retrieving-secrets-from-secrets-management-plugins-in-values)
1. [YAML Aliases](#yaml-aliases)

## Format version

Please note that it is now recommended to declare `format_version` in each `gocd.yaml` file, consistent across all your files.

#### GoCD server version from 20.8.0 and beyond

Supports `format_version` value of `10`. This version removes usage of `blacklist/whitelist` keywords in favour of `includes/ignore`. This is done in a backwards compatible way - you can upgrade the server and plugin first, and update the format_version to 10 after. Just replace `whitelist` by `includes`, and `blacklist` by `ignore`.

Additionally, plugin is also "forwards compatible" since version 0.13.0. If you can't upgrade GoCD to 20.8.0, but want to migrate from `blacklist/whitelist` to `includes/ignore`, you can upgrade the plugin and keep the format_version that you are using. Plugin will migrate keywords under the hood, while your YAML can use `includes/ignore`.