{"id":39790783,"url":"https://github.com/tomzo/gocd-yaml-config-plugin","last_synced_at":"2026-02-28T11:27:59.154Z","repository":{"id":40558541,"uuid":"63266741","full_name":"tomzo/gocd-yaml-config-plugin","owner":"tomzo","description":"Plugin to declare GoCD pipelines and environments configuration in YAML","archived":false,"fork":false,"pushed_at":"2026-02-01T15:48:00.000Z","size":1268,"stargazers_count":212,"open_issues_count":10,"forks_count":95,"subscribers_count":12,"default_branch":"master","last_synced_at":"2026-02-01T16:18:29.541Z","etag":null,"topics":["gocd","pipelines-as-code"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomzo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2016-07-13T17:38:01.000Z","updated_at":"2026-02-01T15:48:03.000Z","dependencies_parsed_at":"2023-02-12T00:30:48.540Z","dependency_job_id":"dbaaad53-a5d0-4c43-8013-1b9861a6b42a","html_url":"https://github.com/tomzo/gocd-yaml-config-plugin","commit_stats":{"total_commits":262,"total_committers":34,"mean_commits":7.705882352941177,"dds":0.6297709923664122,"last_synced_commit":"65bc6672d324f221c91f25c923e5ffff99e89b52"},"previous_names":[],"tags_count":147,"template":false,"template_full_name":null,"purl":"pkg:github/tomzo/gocd-yaml-config-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomzo%2Fgocd-yaml-config-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomzo%2Fgocd-yaml-config-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomzo%2Fgocd-yaml-config-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomzo%2Fgocd-yaml-config-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomzo","download_url":"https://codeload.github.com/tomzo/gocd-yaml-config-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomzo%2Fgocd-yaml-config-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29931585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T09:58:13.507Z","status":"ssl_error","status_checked_at":"2026-02-28T09:57:57.047Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gocd","pipelines-as-code"],"created_at":"2026-01-18T12:15:04.069Z","updated_at":"2026-02-28T11:27:59.114Z","avatar_url":"https://github.com/tomzo.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Google Groups](https://img.shields.io/badge/Google_Groups-user_help-purple)](https://groups.google.com/g/go-cd)\n[![GitHub Discussions](https://img.shields.io/badge/GitHub_discussions-user_\u0026amp;_dev_chat-green)](https://github.com/gocd/gocd/discussions)\n\n# gocd-yaml-config-plugin\n\n[GoCD](https://www.gocd.org) plugin to keep **pipelines** and **environments**\nconfiguration in source-control in [YAML](http://www.yaml.org/).\nSee [this document](https://docs.gocd.org/current/advanced_usage/pipelines_as_code.html)\nto find out what are GoCD configuration repositories.\n\nThis is the second GoCD configuration plugin, which enhances some of shortcomings of\n[JSON configuration plugin](https://github.com/tomzo/gocd-json-config-plugin)\n\n* Format is **concise**. Unlike JSON, there are no unnecessary quotations `\"`, brackets `{}` and commas `,`\n* Tries to **enforce correctness** where possible. By using maps instead of lists and shorter object graphs.\n* Allows to have multiple pipelines and environments in single file. But doesn't force it.\n* **Comments in configuration files** - YAML supports comments,\nso you can explain why pipeline/environment it is configured like this.\n\n# Table of contents\n\n1. [Setup](#setup)\n1. [Example configuration](#example)\n1. [File pattern](#file-pattern)\n1. [Validation](#Validation)\n1. **[Format reference](#Format-reference)**\n1. [Format version](#Format-version)\n1. [Issues and questions](#Issues-and-questions)\n1. [Development](#Development)\n1. [License](#License)\n\n# Setup\n\n**Step 1**: GoCD versions newer than `17.8.0` already have the plugin bundled. You don't need to install anything.\n\nIf you're using GoCD version *older than 17.8.0*, you need to install the plugin in the GoCD server. Download it from\n[the releases page](https://github.com/tomzo/gocd-yaml-config-plugin/releases) and place it on the GoCD server in\n`plugins/external` [directory](https://docs.gocd.org/current/extension_points/plugin_user_guide.html).\n\n\n\n**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.\n\nYou can use the example repository at: `https://github.com/tomzo/gocd-yaml-config-example.git`.\n\nIn 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.\n\n## Example\n\nMore examples are in [test resources](src/test/resources/examples/).\n\n```yaml\n#ci.gocd.yaml\nformat_version: 9\nenvironments:\n  testing:\n    environment_variables:\n      DEPLOYMENT: testing\n    secure_variables:\n      ENV_PASSWORD: \"s\u0026Du#@$xsSa\"\n    pipelines:\n      - example-deploy-testing\n      - build-testing\npipelines:\n  mypipe1: # definition of mypipe1 pipeline\n    group: mygroup # note that the group name can contain only of alphanumeric \u0026 underscore characters\n    display_order: 10\n    label_template: \"${mygit[:8]}\"\n    lock_behavior: none\n    parameters: # list of parameters that can be configured for a pipeline\n      param1: value1\n    materials:\n      mygit: # this is the name of material, the name can contain only of alphanumeric \u0026 underscore characters\n        # keyword git says about type of material and url at once\n        git: https://my.example.org/mygit.git\n        branch: ci\n      myupstream: # this name does not matter, but there should be no 2 materials with the same name\n        # type is optional here, material type is implied based on presence of pipeline and stage fields\n        # type: dependency\n        pipeline: pipe2\n        stage: test\n    stages: # list of stages in order\n      - build: # name of stage\n          clean_workspace: true\n          jobs:\n            csharp: # name of the job\n              resources:\n               - net45\n              artifacts:\n               - build:\n                   source: bin/\n                   destination: build\n               - test:\n                   source: tests/\n                   destination: test-reports/\n               - test:\n                   source: coverage.xml\n              tabs:\n                report: test-reports/index.html\n              tasks: # ordered list of tasks to execute in job csharp\n               - fetch:\n                   pipeline: pipe2\n                   stage: build\n                   job: test\n                   source: test-bin/\n                   destination: bin/\n               - exec: # indicates type of task\n                   command: make\n                   arguments:\n                    - \"VERBOSE=true\"\n               # shorthand for script-executor plugin\n               - script: ./build.sh ci\n```\n\n## File pattern\n\nThe default pattern is `**/*.gocd.yaml,**/*.gocd.yml`, which will recursively search the entire repository for all files ending with `.gocd.yaml` or `.gocd.yml`.\n\nYou can set a custom file pattern per configuration repository using the GoCD configuration UI:\n![yaml pattern config](yaml_file_pattern.png)\n\nOr in the config XML using `\u003cconfiguration\u003e`:\n\n```xml\n\u003cconfig-repos\u003e\n  \u003cconfig-repo pluginId=\"yaml.config.plugin\" id=\"repo1\"\u003e\n    \u003cgit url=\"https://github.com/tomzo/gocd-yaml-config-example.git\" /\u003e\n    \u003cconfiguration\u003e\n      \u003cproperty\u003e\n        \u003ckey\u003efile_pattern\u003c/key\u003e\n        \u003c!-- comma-separate multiple patterns --\u003e\n        \u003cvalue\u003epipelines/build/*.yml,pipelines/lint/*.yml\u003c/value\u003e\n      \u003c/property\u003e\n    \u003c/configuration\u003e\n  \u003c/config-repo\u003e\n\u003c/config-repos\u003e\n```\n\n# Validation\n\nYou can validate if proposed GoCD YAML changes will be accepted by the server. Currently, 2 options are available:\n * Use a [GoCD mergable github action](https://github.com/GaneshSPatil/gocd-mergeable)\n * [Validate from your local machine](#validation-using-cli)\n\n## Validation using CLI\n\n*You may find this [introductory blog post useful](https://kudulab.io/posts/gocd-preflight-validation/).*\n\nThere 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).\n\nYou have several options to configure validation tools on your workstation:\n * 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.\n * 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).\n\nEither way you'll have `gocd` binary in your `PATH` or inside the docker container.\n\n### Syntax validation\n\nThis will check general validity of the yaml file, without talking to the GoCD server:\n```bash\ngocd configrepo syntax --yaml pipeline.gocd.yaml\n```\n\n### Preflight validation\n\nThis command will parse and submit your yaml file to the configured GoCD server.\n```\ngocd configrepo preflight --yaml -r dotnet-dojo pipeline.gocd.yaml\n```\nWhere `-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.\n![config repo id](config_repo_id.png)\n\nFor 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.\n```\ngocd configrepo preflight --yaml pipeline.gocd.yaml\n```\n\n# Format reference\n\nSee [official GoCD XML configuration reference](https://docs.gocd.org/current/configuration/configuration_reference.html)\nfor details about each element. Below is a reference of format supported by this plugin.\nFeel free to improve it!\n\n1. [**Format version**](#format-version)\n1. [Environment](#environment)\n1. [Environment variables](#environment-variables)\n1. [Parameters](#parameters)\n1. [Pipeline](#pipeline)\n    * [Tabs](#tabs)\n    * [Controlling the display order](#display-order-of-pipelines)\n    * [Tracking tool](#tracking-tool)\n    * [Timer](#timer)\n    * [Locking](#pipeline-locking)\n1. [Stage](#stage)\n    * [Approval](#approval)\n1. [Job](#job)\n    * [Property](#property)\n    * [Tab](#tab)\n    * [Many instances](#run-many-instances)\n1. [Tasks](#tasks)\n    * [rake](#rake)\n    * [ant](#ant)\n    * [nant](#nant)\n    * [exec](#exec)\n    * [fetch](#fetch)\n    * [pluggabletask](#plugin)\n    * [script](#script)\n1. [Materials](#materials)\n    * [dependency](#dependency)\n    * [package](#package)\n    * [git](#git)\n    * [svn](#svn)\n    * [perforce](#perforce)\n    * [tfs](#tfs)\n    * [hg](#hg)\n    * [pluggable scm](#pluggable)\n    * [config repo](#configrepo)\n1. [Secure variables](#to-generate-an-encrypted-value)\n1. [Retrieving secrets from Secrets Management plugins in values](#retrieving-secrets-from-secrets-management-plugins-in-values)\n1. [YAML Aliases](#yaml-aliases)\n\n## Format version\n\nPlease note that it is now recommended to declare `format_version` in each `gocd.yaml` file, consistent across all your files.\n\n#### GoCD server version from 20.8.0 and beyond\n\nSupports `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`.\n\nAdditionally, 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`.\n\nUsing a newer `format_version` includes all the behavior of the previous versions too.\n\n```yaml\nformat_version: 10\npipelines:\n  ...\nenvironments:\n```\n\n#### GoCD server version from 19.10.0 and beyond\n\nSupports `format_version` value of `9`. In this version, support of `ignore_for_scheduling` for [dependency materials](#dependency) has been added. Setting this attribute will skip scheduling the pipeline when the dependency material has changed.\n\nUsing a newer `format_version` includes all the behavior of the previous versions too.\n\n#### GoCD server version from 19.9.0 and beyond\n\nSupports `format_version` value of `7` and `8`. In version `7`, support for [properties](#property) has been removed. In version `8`, support for `mingle` as a [tracking tool](#tracking-tool) has been removed.\n\nUsing a newer `format_version` includes all the behavior of the previous versions too.\n\n\n#### GoCD server version from 19.8.0 and beyond\n\nSupports `format_version` value of `6`. In this version, support of `allow_only_on_success` attribute for [approval](#approval) in stage has been added. Setting this attribute to `true` will allow the stage to be manually triggered only if the previous stage has passed successfully.\n\nUsing a newer `format_version` includes all the behavior of the previous versions too.\n\n#### GoCD server version from 19.4.0 to 19.7.0\n\nSupports `format_version` value of `5`. In this version, support of `username` and `encrypted_password` for [git](#git-material-update) and [hg](#hg-material-update) material has been added. In addition to that, [hg](#hg-material-update) will also support `branch` attribute.\n\nUsing a newer `format_version` includes all the behavior of the previous versions too.\n\n\n#### GoCD server version 19.3.0\n\nSupports `format_version` value of `4`. In this version, support has been added to control the [display order of pipelines](#display-order-of-pipelines).\n\nThis server version also supports `format_version` of `3` and `2`. Using a newer `format_version` includes all the behavior of the previous versions too.\n\n#### GoCD server version from 18.7.0 to 19.2.0\n\nSupports `format_version` value of `3`. In this version [fetch artifact](#fetch) format was changed to include `artifact_origin`.\n\nThis server version also supports `format_version` of `2`. Using a newer `format_version` includes all the behavior of the previous versions too.\n\n#### GoCD server version from 17.12.0 to 18.6.0\n\nSupports `format_version` value of `2`. In this version [pipeline locking](#pipeline-locking) behavior was changed.\n\n#### GoCD server version up to 17.11.0\n\nSupports `format_version` value of `1`. This is the initial version.\n\n# Pipeline\n\nA minimal [pipeline](https://docs.gocd.org/current/configuration/configuration_reference.html#pipeline) configuration must contain:\n * pipeline name - as a key in hash\n * [materials](#materials) - a **hash**\n * [stages](#stage) - a **list** or a `template` - as a key in hash\n\n```yaml\nmypipe:\n  group: mygroup\n  materials:\n    mygit:\n      git: http://example.com/mygit.git\n  stages:\n    - build:\n        jobs:\n          build:\n            tasks:\n             - exec:\n                 command: make\n```\n\nAll elements available on a pipeline object are:\n\n * `group`\n * `label_template`\n * [locking](#pipeline-locking)\n * [tracking_tool](#tracking-tool) or `mingle`\n * [timer](#timer)\n * [environment_variables](#environment-variables)\n * [parameters](#parameters)\n * `secure_variables`\n * [materials](#materials)\n * [stages](#stage)\n * `template`\n\n```yaml\npipe2:\n  group: group1\n  label_template: \"foo-1.0-${COUNT}\"\n  lock_behavior: none\n  tracking_tool:\n    link: \"http://your-trackingtool/yourproject/${ID}\"\n    regex: \"evo-(\\\\d+)\"\n  timer:\n    spec: \"0 15 10 * * ? *\"\n  environment_variables:\n    DEPLOYMENT: testing\n  secure_variables:\n    ENV_PASSWORD: \"s\u0026Du#@$xsSa\"\n  materials:\n    ...\n  stages:\n    ...\n```\n#### Referencing an existing template in a pipeline:\n```yaml\nmypipe:\n  group: group1\n  label_template: \"foo-1.0-${COUNT}\"\n  lock_behavior: none\n  parameters:\n    param1: value\n  materials:\n    mygit:\n      git: http://example.com/mygit.git\n  template: template1\n```\n\nPlease note:\n * Pipeline declares a group to which it belongs\n\n\u003ca name=\"display-order-of-pipelines\"/\u003e\n\n### Controlling the display order\n\nWhen `format_version` is `4` (see [above](#format-version)), the order of display of pipelines on the GoCD dashboard can be influenced by setting the `display_order` property.\n\n- This is an integer property and the pipelines in a pipeline group will be ordered by this value.\n- The default value for this property is `-1`.\n- Pipelines defined in GoCD's config XML will also default to -1.\n- If multiple pipelines have the same `display_order` value, their order relative to each other will be indeterminate.\n\n```yaml\nmypipeline1:\n  group: group1\n  display_order: 10\n\nmypipeline2:\n  group: group1\n  display_order: -10\n```\n\nIn the above example, since both pipelines are in the same group, `pipeline2` will be shown ahead of `pipeline1`. If any pipelines are defined in the GoCD config XML, then they will appear in between these two pipelines.\n\n### Tracking tool\n\n```yaml\ntracking_tool:\n  link: \"http://your-trackingtool/yourproject/${ID}\"\n  regex: \"evo-(\\\\d+)\"\n```\n\n### Timer\n\n```yaml\ntimer:\n  spec: \"0 15 10 * * ? *\"\n  only_on_changes: yes\n```\n\nSee [Quartz](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html) about writing cron-like schedules.\n\n### Pipeline locking\n\nFor **GoCD \u003e= 17.12 and `format_version: 2` and above**:\n\n```yaml\nlock_behavior: none\n```\n\nWhere `lock_behavior` is defined as in [GoCD documentation](https://docs.gocd.org/17.12.0/configuration/admin_lock_pipelines.html) can be one of:\n\n * `lockOnFailure` - same as `locking: true`\n * `unlockWhenFinished`\n * `none` - same `locking: false`\n\nFor **GoCD \u003c 17.12 and `format_version: 1`**:\n\n`locking: on`\n\nWhere `locking` is a [boolean](#boolean-values).\n\n\n## Stage\n\nA minimal stage must contain `jobs:` element or `tasks:` in [single-job stage case](single-job-stage).\n```yaml\nbuild:\n  jobs:\n    firstJob:\n      ...\n    secondJob:\n      ...\n```\n\nA custom stage:\n```yaml\ntest:\n  fetch_materials: yes\n  keep_artifacts: yes\n  clean_workspace: yes\n  approval:\n    type: manual\n    roles:\n      - manager\n    users:\n      - john\n  environment_variables:\n    TEST_NUM: 1\n  secure_variables:\n    PASSWORD: \"!@ESsdD323#sdu\"\n  jobs:\n    one:\n      ...\n    two:\n      ...\n```\n\n * When `keep_artifacts` is set to `true` GoCD will never delete artifacts in this stage. This is equivalent of XML's `artifactCleanupProhibited`. By default this is `false`.\n\n### Approval\n\nStage can have [approval](https://docs.gocd.org/current/configuration/configuration_reference.html#approval),\n which is `success` by default. There are 2 ways to declare approval:\n```yaml\napproval: manual\n```\nIf you need to set associated users or roles:\n```yaml\napproval:\n  type: manual\n  allow_only_on_success: true\n  roles:\n    - manager\n  users:\n    - john\n```\n\nYou can set `allow_only_on_success` to allow manual trigger only if the previous stage run is successful. The default value is `false`.\n\n## Job\n\n[Job](https://docs.gocd.org/current/configuration/configuration_reference.html#job) is a hash starting with jobs name:\n\n```yaml\ntest:\n  timeout: 5\n  run_instances: 7\n  environment_variables:\n    LD_LIBRARY_PATH: .\n  tabs:\n    test: results.xml\n  resources:\n    - linux\n  artifacts:\n    - test:\n        source: src\n        destination: dest\n    - build:\n        source: bin\n    - external:\n        id: docker-release-candidate\n        store_id: dockerhub\n        configuration:\n          options:\n            Image: gocd/gocd-demo\n            Tag: v${GO_PIPELINE_LABEL}\n          secure_options:\n            some_secure_property: \"!@ESsdD323#sdu\"\n  tasks:\n    ...\n```\n\n*Note: timeout is added since 0.2.0 version of yaml plugin*\n\n### Elastic agent profile id\n\nJob configuration may define elastic agents profile id, as such:\n```yaml\nelastic_profile_id: \"docker.unit-test\"\n```\n\nIt MUST NOT be specified along with `resources`.\nAvailable in GoCD server since v16.12.0, yaml plugin 0.4.0.\n\n### Artifacts\n\nThere are 3 types of artifacts recognized by GoCD. `Build` and `Test` artifacts are stored on the GoCD server.\nThe source and the destination of the artifact that should be stored on the GoCD server must be specified.\n\n#### Build\n\n```yaml\n- build:\n    source: bin\n    destination: binaries\n```\n\n#### Test\n\n```yaml\n- test:\n    source: reports\n    destination: test-reports\n```\n\n#### External\n\nArtifacts of type `external` are stored in an artifact store outside of GoCD.\nThe external artifact store's configuration must be created in the main GoCD config. Support for external artifact store config to be checked in as yaml is not available.\nThe external artifact store is referenced by the `store_id`. The build specific artifact details that the artifact plugin needs to publish the artifact is provided as `configuration`.\n\n```yaml\n- external:\n    id: docker-release-candidate\n    store_id: dockerhub\n    configuration:\n      options:\n        Image: gocd/gocd-demo\n        Tag: v${GO_PIPELINE_LABEL}\n      secure_options:\n        some_secure_property: \"!@ESsdD323#sdu\"\n```\n\n[S3 plugin 2.x](https://github.com/Diogomrol/gocd-s3-artifact-plugin) example usage:\n```yaml\n- external:\n    id: pkg\n    store_id: s3-eu-west-1\n    configuration:\n      options:\n        Source: installers/target/\n        Destination: ${GO_ARTIFACT_LOCATOR}\n```\n\n### Run many instances\n\nPart of job object can be [number of job to runs](https://docs.gocd.org/current/advanced_usage/admin_spawn_multiple_jobs.html):\n```yaml\nrun_instances: 7\n```\nOr to run on all agents:\n```yaml\nrun_instances: all\n```\n\n### Tabs\n\nTabs are a hash with `\u003ctab-name\u003e: \u003cpath\u003e` pairs.\nPath should exist in GoCD servers artifacts.\n```yaml\ntabs:\n  tests: test-reports/index.html\n  gauge: functional-reports/index.html\n```\n\n### Property\n**DEPRECATION NOTICE: Since GoCD version 19.9 and format_version 7, properties are no longer supported**\n\nJob can have properties, declared as a hash:\n```yaml\nproperties:\n  cov1: # this is the name of property\n    source: test.xml\n    xpath: \"substring-before(//report/data/all/coverage[starts-with(@type,\\u0027class\\u0027)]/@value, \\u0027%\\u0027)\"\n  performance.ind1.mbps:\n    source: PerfTestReport.xml\n    xpath: \"//PerformanceSuiteReport/WriteOnly/MBps\"\n```\n\n### Single job stage\n\nA common use case is that stage has only one job. This plugin provides a shorthand\nto declared such stages - just **omit the `jobs:` and job name** from configuration tree.\nYou can then declare job and stage options on the same (stage) level:\n```yaml\nstages:\n  - build:\n      approval: manual\n      resources:\n        - cpp\n      tasks:\n       - exec:\n           command: make\n```\nAbove configuration declares `build` **stage** with `build` **job** which executes `make` task.\n\n## Materials\n\n### Git\n\nMinimal configuration of a [**git** pipeline material](https://docs.gocd.org/current/configuration/configuration_reference.html#git):\n * material name is `mygit`\n * git repository url is `http://example.com/mygit.git`\n\n```yaml\nmygit:\n  git: http://example.com/mygit.git\n```\n\nAbove can be also written more explicitly:\n```yaml\nmygit:\n  type: git\n  url: http://example.com/mygit.git\n```\n\nMore customized git material is possible:\n```yaml\ngitMaterial1:\n  git: \"https://my.git.repository.com\"\n  branch: feature12\n  ignore:\n    - externals/**/*.*\n    - tools/**/*.*\n# For GoCD \u003c 20.8.0 or plugin version \u003c 0.13.0, you need to use blacklist instead of ignore:\n  blacklist:\n    - externals/**/*.*\n    - tools/**/*.*\n  destination: dir1\n  auto_update: false\n  shallow_clone: true\n```\n\nSince GoCD `\u003e= 16.7.0` includes is also supported,\nyou can specify `includes` **instead** of `ignore`, as such\n```yaml\ngitMaterial1:\n  git: \"git@my.git.repository.com\"\n  branch: \"feature12\"\n  includes:\n    - src/**/*.*\n# For GoCD \u003c 20.8.0 or plugin version \u003c 0.13.0, you need to use whitelist instead:\n  whitelist:\n    - src/**/*.*\n```\n\n\u003ca name=\"git-material-update\"/\u003e\n\nFor **GoCD \u003e= 19.4.0 and `format_version: 5` and above**:\n\nYou are advised to utilize `username` and `encrypted_password` for passing in material credentials as:\n```yaml\ngitMaterial1:\n  git: \"https://my.git.repository.com\"\n  branch: feature12\n  username: my_username\n  encrypted_password: encrypted_value\n```\n\n- Instead of `encrypted_password` you may specify `password` but `encrypted_password` makes more sense considering that the value is stored in SCM.\n- Specifying credentials both in `attributes` and `url` will result in a validation error e.g.\n  ```log\n    INVALID MERGED CONFIGURATION\n    Number of errors: 1+\n    1. Ambiguous credentials, must be provided either in URL or as attributes.;;\n    - For Config Repo: https://your.config.repo.url at cbb047d78c239ab23b9565099e800c6fe4cc0anc\n  ```\n\n### Svn\n\nFor details about each option, see [GoCD XML reference](https://docs.gocd.org/current/configuration/configuration_reference.html#svn)\n```yaml\nsvnMaterial1:\n  svn: \"http://svn\"\n  username: \"user1\"\n  encrypted_password: \"encrypted_value\"\n  check_externals: true\n  ignore:\n    - tools\n    - lib\n# For GoCD \u003c 20.8.0 or plugin version \u003c 0.13.0, you need to use blacklist instead of ignore:\n  blacklist:\n    - tools\n    - lib\n  destination: destDir1\n  auto_update: false\n```\nInstead of `encrypted_password` you can specify `password`.\n\n### Hg\n\n```yaml\nhgMaterial1:\n  hg: repos/myhg\n  ignore:\n    - externals\n    - tools\n# For GoCD \u003c 20.8.0 or plugin version \u003c 0.13.0, you need to use blacklist instead of ignore:\n  blacklist:\n    - externals\n    - tools\n  destination: dir1\n  auto_update: false\n  username: my_username\n  encrypted_password: encrypted_value\n  branch: feature\n```\n\u003ca name=\"hg-material-update\"/\u003e\n\nFor **GoCD \u003e= 19.4.0 and `format_version: 5` and above**:\n\nYou are advised to utilize `username` and `encrypted_password` for passing in material credentials as:\n```yaml\nhgMaterial1:\n  hg: repos/myhg\n  username: my_username\n  encrypted_password: encrypted_value\n```\n\n- Instead of `encrypted_password` you may specify `password` but `encrypted_password` makes more sense considering that the value is stored in SCM.\n- Specifying credentials both in `attributes` and `url` will result in a validation error e.g.\n  ```log\n    INVALID MERGED CONFIGURATION\n    Number of errors: 1+\n    1. Ambiguous credentials, must be provided either in URL or as attributes.;;\n    - For Config Repo: https://your.config.repo.url at cbb047d78c239ab23b9565099e800c6fe4cc0anc\n  ```\n\nIn addition to that, you can also leverage `branch` attribute to specify the branch for material\n\n```yaml\nhgMaterial1:\n  hg: repos/myhg\n  branch: feature\n```\n\n\n### Perforce\n\n```yaml\np4Material1:\n  p4: \"host.domain.com:12345\"\n  username: johndoe\n  encrypted_password: encrypted_value\n  use_tickets: false\n  view: |\n    //depot/external... //ws/external...\n    //depot/tools... //ws/external...\n  ignore:\n    - externals\n    - tools\n# For GoCD \u003c 20.8.0 or plugin version \u003c 0.13.0, you need to use blacklist instead of ignore:\n  blacklist:\n    - externals\n    - tools\n  auto_update: false\n```\n\nInstead of `encrypted_password` you can specify `password`.\n\n### Tfs\n\n*TODO: - not supported by yaml plugin yet*\n\n### Pluggable\n\n```yaml\nmyPluggableGit:\n  scm: someScmGitRepositoryId\n  destination: destinationDir\n  ignore:\n    - dir1\n    - dir2\n# For GoCD \u003c 20.8.0 or plugin version \u003c 0.13.0, you need to use blacklist instead of ignore:\n  blacklist:\n    - dir1\n    - dir2\n```\n\nSince GoCD `\u003e= 19.2.0` defining new pluggable materials that are not defined\nin the GoCD server is supported.\n\n```yaml\nmyPluggableGit:\n  plugin_configuration:\n    id: plugin_Id\n    version: 1 #plugin version\n  options:\n    url: git@github.com:tomzo/gocd-yaml-config-plugin.git\n  secure_options:\n    password: \"encrypted_value\"\n  destination: destinationDir\n  ignore:\n    - dir1\n    - dir2\n# For GoCD \u003c 20.8.0 or plugin version \u003c 0.13.0, you need to use blacklist instead of ignore:\n  blacklist:\n    - dir1\n    - dir2\n```\n\n### Configrepo\n\nThis is a convenience for shorter and more consistent material declaration.\nWhen configuration repository is the same as one of pipeline materials,\nthen you usually need to repeat definitions in XML and in JSON, for example:\n\n```yaml\nmaterials:\n  foo:\n    git: \"https://github.com/tomzo/gocd-json-config-example.git\",\n    branch: ci\n```\n\nAnd in server XML:\n```xml\n\u003cconfig-repos\u003e\n   \u003cconfig-repo pluginId=\"yaml.config.plugin\" id=\"repo1\"\u003e\n     \u003cgit url=\"https://github.com/tomzo/gocd-json-config-example.git\" branch=\"ci\" /\u003e\n   \u003c/config-repo\u003e\n\u003c/config-repos\u003e\n```\n\nNotice that url and branch is repeated. This is inconvenient in case when you move repository,\nbecause it requires 2 updates, in code and in server XML.\n\nUsing  **`configrepo` material type**, above repetition can be avoided,\nlast example can be refactored into:\n\n```yaml\nmaterials:\n  foo:\n    type: configrepo\n```\n\nServer interprets `configrepo` material in this way:\n\n\u003e Clone the material configuration of the repository we are parsing **as is in XML** and replace **name, destination and filters (includes/ignore)**,\nthen use the modified clone in place of `configrepo` material.\n\n### Dependency\n\nTo add a dependency on another pipeline stage:\n```yaml\nmydependency:\n  pipeline: upstream-pipeline-1\n  stage: test\n  ignore_for_scheduling: false\n```\n\n**Note: `mydependency` is the name of material - it must be unique**\n\n### Package\n\n```yaml\nmyapt:\n  package: apt-repo-id\n```\n\n## Tasks\n\nEvery task is a hash starting with its type.\nType can be `exec`, `ant`, `nant`, `rake`, `fetch`, `plugin` or `script`.\n\n```yaml\n\u003ctype\u003e:\n  \u003ctask-prop1\u003e: \u003cprop1-value\u003e\n```\n\nOptionally any task can have `run_if` and `on_cancel`.\n\n * `run_if` is a string. Valid values are `passed`, `failed`, `any`\n * `on_cancel` is a task object. Same rules apply as to tasks described on this page.\n See [rake example](#rake).\n\n### Exec\n\n```yaml\nexec:\n  run_if: any\n  working_directory: dir\n  command: make\n  arguments:\n   - -j3\n   - docs\n   - install\n```\n\n### Ant\n\n```yaml\nant:\n  build_file: mybuild.xml\n  target: compile\n  run_if: passed\n```\n\n### Nant\n\n```yaml\nnant:\n  run_if: passed\n  working_directory: \"script/build/123\"\n  build_file: FilePath\n  target: Build\n  nant_path: NantExe\n```\n\n### Rake\n\nA minimal rake task with default values is very short\n```yaml\nrake:\n```\n\nA complete rake example:\n```yaml\nrake:\n  run_if: passed\n  working_directory: sample-project\n  build_file: SomeRakefile\n  target: build\n  on_cancel:\n    rake:\n      working_directory: sample-project\n      build_file: CancelRakefile\n      target: cancel\n```\n\n### Fetch\n\n#### Fetch artifact from the GoCD server\n\n```yaml\nfetch:\n  run_if: any\n  artifact_origin: gocd # default value\n  pipeline: pipe2\n  stage: upstream_stage\n  job: upstream_job\n  is_file: yes\n  source: result\n  destination: test\n```\n\n * `artifact_origin` if not specified then, defaults to `gocd`, which is consistent with previous `format_version` 1 and 2.\n * `pipeline` if not specified, then defaults to current pipeline.\n\n#### Fetch artifact from an external artifact store\n\n```yaml\nfetch:\n  run_if: any\n  artifact_origin: external\n  pipeline: pipe2\n  stage: upstream_stage\n  job: upstream_job\n  artifact_id: upstream_artifact_id\n  configuration:\n    options:\n      DestOnAgent: foo\n    secure_options:\n      some_secure_property: \"!@ESsdD323#sdu\"\n```\n\n[S3 plugin 2.x](https://github.com/Diogomrol/gocd-s3-artifact-plugin) example usage:\n```yaml\n- fetch:\n    artifact_origin: external\n    stage: plan\n    job: plan\n    artifact_id: plan\n    configuration:\n      options:\n        IsFile: true\n        Destination: terraform\n        Source: deployment.tfplan\n```\n\n### Plugin\n\n```yaml\nplugin:\n  options:\n    ConverterType: jsunit\n  secure_options:\n    password: \"ssd#%fFS*!Esx\"\n  run_if: failed\n  configuration:\n    id: xunit.converter.task.plugin\n    version: 1\n```\n\n### Script\n\nBecause [script-executor plugin](https://github.com/gocd-contrib/script-executor-task)\nrequires quite a lot of boiler-plate configuration\nthere is a shorthand for defining tasks with it:\n```yaml\nscript: ./build.sh compile\n```\nAbove is equivalent of\n```yaml\nplugin:\n  options:\n    script: ./build.sh compile\n  configuration:\n    id: script-executor\n    version: 1\n```\n\nYou can declare **multi-line scripts** too:\n```yaml\nscript: |\n  ./build.sh compile\n  make test\n```\nAbove executes a 2-line script:\n```bash\n./build.sh compile\nmake test\n```\n\nIf you want to **execute** a single *long* line script, but break it into multiple lines in YAML,\nyou can do this with `\u003e` as such:\n```yaml\nscript: \u003e\n  ./build.sh compile \u0026\u0026\n  make test\n```\nAbove executes a **single line** script:\n```bash\n./build.sh compile \u0026\u0026 make test\n```\n\n## Environment\n\n*NOTE: The agents should be a guid, which is currently impossible to get for user*\n\n```yaml\ntesting:\n  environment_variables:\n    DEPLOYMENT: testing\n  secure_variables:\n    ENV_PASSWORD: \"s\u0026Du#@$xsSa\"\n  pipelines:\n    - example-deploy-testing\n    - build-testing\n  agents:\n    - 123\n```\n\n### Environment variables\n\n[Environment variables](https://docs.gocd.org/current/configuration/configuration_reference.html#environmentvariables)\n can be declared in **Environments, Pipelines, Stages and Jobs**.\n\nIn YAML you have 2 keywords for *secure* (encrypted) variables and standard variables.\n```yaml\nenvironment_variables:\n  DEPLOYMENT: testing\n  FOO: bar\nsecure_variables:\n  # this value is encrypted by Go's private key (Note in 16.7.0 there is no easy way to obtain such value yet)\n  MY_PASSWORD: \"s\u0026Du#@$xsSa\"\n```\n\n### Parameters\n\n[Parameters](https://docs.go.cd/current/configuration/configuration_reference.html#params) can be declared at the pipeline level.\n\n```yaml\nparameters:\n  param1: value1\n  production: no\n```\n\n\n### To generate an encrypted value\n\n**For versions of GoCD \u003e= 17.1:**\n\nSee the [encryption API](https://api.gocd.org/current/#encrypt-a-plain-text-value).\n\n**For versions of GoCD \u003c= 16.12:**\n\n\u003e There is no easy way to generate obtain [encrypted value](https://github.com/tomzo/gocd-yaml-config-plugin/issues/5) from GoServer, alternatively you can login into go-server and execute the following command to generate encrypted value\n\n```sh\nsudo -u go bash -c 'echo -n 'YOUR-INPUT' | openssl enc -des-cbc -a -iv 0 -K $(cat /etc/go/cipher)'\n```\n\n### Retrieving secrets from Secrets Management plugins in values\n\nRather than using secure variables encrypted in values and source controlled, you can use [Secrets Management](https://docs.gocd.org/current/configuration/secrets_management.html) plugins\nto store secrets within various backends and have them dynamically retrieved at runtime.\n\nWith any of the corresponding YAML fields documented [here](https://docs.gocd.org/current/configuration/secrets_management.html#step-4---define-secret-params) you\ncan use the special syntax to denote a secret to be looked up.\n\nNote that **quoting the values is important** since braces (`{`, `}`) are important in YAML, as a superset of JSON.\n\n```yaml\nenvironment_variables:\n  DEPLOYMENT: testing\n  FOO: bar\n  # this value retrieves the `testing_password` secret from the `sample_secret`\n  # configuration of whichever secrets plugin is appropriate\n  MY_PASSWORD: \"{{SECRET:[sample_secret][testing_password]\"\n```\n\n### Boolean values\n\nAmong all configuration elements there are boolean values, which can be defined\nusing any of the keywords below (as in [yaml specs](http://yaml.org/type/bool.html)):\n * **true** - `y|Y|yes|Yes|YES|true|True|TRUE|on|On|ON`\n * **false** - `n|N|no|No|NO|false|False|FALSE|off|Off|OFF`\n\n## YAML Aliases\n\nYAML Aliases ([specification](http://www.yaml.org/spec/1.2/spec.html#id2786196)) are supported and provide a way to avoid duplication.\n\nAliases can be defined anywhere in the configuration as long as they are valid configuration elements.\n\n```yaml\n- exec:\n  command: make\n  arguments:\n   - clean\n   - \u0026verbose_arg \"VERBOSE=true\" # define the alias\n- exec:\n  command: make\n  arguments:\n   - world\n   - *verbose_arg # use the alias\n```\n\nThere is also a dedicated top-level `common` section which allows you to have all aliases in one place and where you don't need to worry about correct placement within the configuration.\n\n```yaml\nformat_version: 4\ncommon:\n  verbose_arg: \u0026verbose_arg \"VERBOSE=true\"\n  build_tasks: \u0026build_tasks\n    - exec:\n        command: make\n        arguments:\n         - clean\n    - exec:\n        command: make\n        arguments:\n         - world\npipelines:\n  pipe1:\n    stages:\n      - build:\n          jobs:\n            build:\n              tasks: *build_tasks\n            test:\n              tasks:\n               - *build_tasks # task list aliases can also be mixed with additional tasks in the same job\n               - exec:\n                   command: make\n                   arguments:\n                    - test\n```\n\nSimilarly stages can be re-used:\n```yaml\nformat_version: 4\ncommon:\n  build_stages: \u0026build_stages\n    - stage1:\n        jobs:\n          # ...\n    - stage2:\n        jobs:\n          # ...\n\npipelines:\n  pipeline_one:\n    stages: *build_stages\n\n  pipeline_two:\n    stages:\n      - *build_stages\n      - stage3:\n        jobs:\n          # ...\n```\n\n\n# Issues and questions\n\n *  If you have **questions on usage**, please ask them on the GoCD [Google Groups forum](https://groups.google.com/g/go-cd) or \n[GitHub Discussions](https://github.com/gocd/gocd/discussions).\n * If you think there is a bug, or you have an idea for a feature and *you are not sure if it's plugin's or [GoCD](https://github.com/gocd/gocd/issues) fault/responsibity*, please ask on the chat first too.\n\nPlease note this brief overview of what is done by the plugin:\n * parsing yaml into json when GoCD server asks for it.\n\nAnd this is done by the GoCD server:\n * complex logic merging multiple config repo sources and XML\n * validation of pipelines/stages/jobs/tasks domain\n * any UI rendering\n\n# Development\n\n## Environment setup\n\nTo build and test this plugin, you'll need java jdk \u003e= 11.\n\nIf you have local java environment, then you may run all tests and create a ready to use jar with:\n```bash\n./gradlew test jar\n```\n\n## Building with docker and dojo\n\nYou don't need to setup java on your host, if you are fine with using docker and [Dojo](https://github.com/kudulab/dojo).\nThis is actually how our GoCD builds the plugin:\n```sh\ndojo \"gradle test jar\"\n```\n\nAssuming you already have a working docker, On OSX, you can install with homebrew:\n```\nbrew install kudulab/homebrew-dojo-osx/dojo\n```\nA manual install is another option:\n```sh\nversion=\"0.9.0\"\n# on Linux:\nwget -O /tmp/dojo https://github.com/kudulab/dojo/releases/download/${version}/dojo_linux_amd64\n# or on Darwin:\n# wget -O /tmp/dojo https://github.com/kudulab/dojo/releases/download/${version}/dojo_darwin_amd64\nchmod +x /tmp/dojo\nmv /tmp/dojo /usr/bin/dojo\n```\n\nThen enter a docker container with java and gradle pre-installed, by running following command at the root of the project:\n```\ndojo\n```\n\n## Versioning\n\nWe use semantic versioning.\n\nIf you are submitting a new feature or patch, please bump the version in `build.gradle`.\n\n## Tests structure\n\nThere are [examples of yaml partials](src/test/resources/parts) and\n their resulting json to be sent to GoCD server. If something is not working right\n we can always add a new case covering exact yaml that user has and json that we\n expect on server side.\n\n\n# License\n\nCopyright 2020 Tomasz Sętkowski\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomzo%2Fgocd-yaml-config-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomzo%2Fgocd-yaml-config-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomzo%2Fgocd-yaml-config-plugin/lists"}