A GoCD plugin that allows maintaining pipelines and environments in source control using a DSL written in the groovy language.
This plugin evaluates untrusted code on the GoCD server. A malicious script can do significant damage (steal keys and secrets, remove files and directories, install malware, etc). As such, please use this plugin only with GoCD servers and repositories where you completely trust your users.
Download the plugin jar from the downloads page and place the jar file on the GoCD server in plugins/external
directory.
Add config-repos
element right above first <pipelines />
. Then you can add any number of repository configuration repositories as such:
<config-repos>
<config-repo pluginId="cd.go.contrib.plugins.configrepo.groovy" id="my-project">
<git url="https://github.com/gocd-contrib/gocd-groovy-dsl-config-plugin.git" />
</config-repo>
</config-repos>
The plugin will now scan and read files ending with the extension .gocd.groovy
and setup pipelines defined in those files.
There are some basic standalone linting abilities provided by the plugin:
java -jar groovy-dsl-plugin.jar syntax file1
$ java -jar groovy-dsl-plugin.jar
Usage: java -jar groovy-dsl-plugin.jar [options] [command] [command options]
Options:
--help, -h
print this help
Commands:
syntax perform syntax checking of specified file
Usage: syntax [options] [file|-]
Options:
--help, -h
print this help
--json, -j
show generated json for the config
Default: false
Generally speaking, the philosophy of this plugin is to allow for IDE and Groovy language-driven support rather than providing static documentation of the structure as with other non-language-based GoCD "pipelines as code" plugins. Alongside getting clues from examples, we'd generally suggest following the below steps to set up an IDE with the DSL dependency and being able to benefit from auto-completion/suggests as well as viewing the API documentation inline with editing.
If you're using an IDE like IntelliJ or Eclipse, you can import the dsl.jar
file from the downloads page, or using the following maven co-ordinates in your build script:
<!-- maven -->
<dependency>
<groupId>cd.go.groovydsl</groupId>
<artifactId>dsl</artifactId>
<!-- get version from https://mvnrepository.com/artifact/cd.go.groovydsl/dsl -->
<version>XXX</version>
</dependency>
// groovy build.gradle
dependencies {
// get version from https://mvnrepository.com/artifact/cd.go.groovydsl/dsl
compileOnly group: 'cd.go.groovydsl', name: 'dsl', version: 'XXX'
}
If you don't use an IDE, an alternative is to use the API Javadocs. Since the intent is for this to be downloaded and viewing in an IDE it is not published somewhere statically, but you can download/view localy:
dsl-${version}-javadoc.jar
index.html
in a browserOften you would want to run your builds against multiple branches and PRs. Manually configuring pipelines/workflow for each branch/PR could be cumbersome. The plugin provides an ability to templatize a pipeline or an entire workflow to run your builds against each branch and PR. Once a template is defined, the plugin scans the configured repository at a regular interval and for each available branch/PR it builds the corresponding pipelines.
The plugin also provides notification capability, you can configure the plugin to notify your pull requests with the build status.
For a working example, refer to the Groovy Script which generates the PR workflow
under the pipeline group gocd-pull_8567-Groovy_plugin_branch_PR_feature_example
on https://build.gocd.org. You will have to login as Guest user to view this pipeline group.
You can refer to PR support examples for comprehensive examples for each provider.
Here is a simple example of the DSL, there are more examples in the examples directory.
import cd.go.contrib.plugins.configrepo.groovy.dsl.*
GoCD.script {
pipelines {
pipeline('build') {
group = 'go-cd'
lockBehavior = 'lockOnFailure'
trackingTool {
link = 'https://github.com/gocd-contrib/gocd-groovy-dsl-config-plugin/issues/${ID}'
regex = ~/##(\d+)/
}
environmentVariables = [
'pipeline-var': 'pipeline-value'
]
materials {
git('my-repo') {
url = 'https://github.com/gocd-contrib/gocd-groovy-dsl-config-plugin'
branch = 'master'
blacklist = ['README.md', "examples/**/*"]
}
}
stages {
stage('test') {
environmentVariables = [
'stage-var': 'stage-value'
]
jobs {
job('build') {
tasks {
bash {
commandString = "git clean -fdx"
}
bash {
commandString = './gradlew clean assemble test'
}
}
}
}
}
}
}
}
}
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.