diff --git a/content/templates/_index.md b/content/templates/_index.md index f4f4beb88..e6eb3ec4a 100644 --- a/content/templates/_index.md +++ b/content/templates/_index.md @@ -8,3 +8,117 @@ menu: main: weight: 405 --- + +A template is a pipeline with one to many defined steps that can be sourced into another pipeline. Templates can live in any repository in a [source control system](/docs/concepts/infrastructure/server/source/) and are expanded at compile time to create the final executable pipeline. + +Templates can take the form of generalized workflows across repositories or complex workflows like matrices in a single build. + +{{% alert color="warning" %}} +The following YAML tags are not valid inside a template pipeline: + +* `services:` +* `secrets:` +* `stages:` +* `templates:` +{{% /alert %}} + +## Template Engines + +### Format + +By default, templates utilize the Go template language unless otherwise specified. You may opt to specify the `format` key to switch the template language to one of the following: + +* `format: go` +* `format: golang` +* `format: ""` +* `format: starlark` + +### Go Template + +[Go Templates](https://golang.org/pkg/text/template/) is the default formatter for building out template pipelines. We extend Go's built-in template functions by utilizing the [sprig library](http://masterminds.github.io/sprig/) in the engine to allow for more options on top of the Go template syntax. + +Let's take a look at a basic template: + +{{% alert color="tip" %}} +For this example we will call it `build.yml` but the YAML does not have a required name. +{{% /alert %}} + +```yaml +metadata: + template: true + +steps: + - name: Test and Build + commands: + - go test ./... + - go build + image: {{ .image }} + pull: always + ruleset: + event: [ push, pull_request ] +``` + +The caller of this template could look like: + +```yaml +version: "1" +templates: + - name: go + source: github.com/octocat/hello-world/.vela/build.yml + format: go + type: github + +steps: + - name: sample + template: + name: go + vars: + image: golang:latest +``` + +### Starlark + +[Starlark](https://github.com/bazelbuild/starlark) is a configuration language that was designed for the [Bazel build system](https://bazel.build/). The language is a [Python](https://www.python.org/) dialect that exists for advanced configuration management that can require complex structures. The language is dynamically typed and allows for all sorts of language-esque primitives to make writing large configuration files more manageable. + +It is recommended users read the [Starlark Spec](https://github.com/bazelbuild/starlark/blob/master/spec.md) to understand the syntax differences between Python and Starlark. Python IDE tools are compatible with Starlark to assist users in writing their `.star` or `.py` template pipelines. + +Let's take a look at a basic template: + +{{% alert color="tip" %}} +For this example we will call it `build.star` but the file does not have a required name. +{{% /alert %}} + +```python +def main(ctx): + return { + 'version': '1', + 'steps': [ + { + 'name': 'build', + 'image': ctx["vars"]["image"], + 'commands': [ + 'go build', + 'go test', + ] + }, + ], +} +``` + +The caller of this template could look like: + +```yaml +version: "1" +templates: + - name: starlark + source: github.com/octocat/hello-world/.vela/build.star + format: starlark + type: github + +steps: + - name: sample + template: + name: starlark + vars: + image: golang:latest +``` diff --git a/content/templates/overview.md b/content/templates/overview.md deleted file mode 100644 index 0bc902823..000000000 --- a/content/templates/overview.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "Overview" -linkTitle: "Overview" -description: > - Learn about Templates for Vela. ---- - -A template is a pipeline with one to many defined steps that can be sourced into another pipeline. Templates can live in any repository in a [source control system](/docs/concepts/infrastructure/server/source/) and are expanded at compile time to create the final executable pipeline. - -Templates can take the form of generalized workflows across repositories or complex workflows like matrices in a single build. - -{{% alert color="warning" %}} -The following YAML tags are not valid inside a template pipeline: - -* `services:` -* `secrets:` -* `stages:` -* `templates:` -{{% /alert %}} - -## Template Engines - -At this time the only supported template engine is [Go Templates](https://golang.org/pkg/text/template/). We extend Go's built-in template functions by utilizing the [sprig library](http://masterminds.github.io/sprig/) in the engine to allow for more options on top of the Go template syntax. - -Let's take a look at a basic template: - -{{% alert color="tip" %}} -For this example we will call it build.yml but the YAML does not have a required name. -{{% /alert %}} - -```yaml -metadata: - template: true - -steps: - - name: Test and Build - commands: - - go test ./... - - go build - image: {{ .image }} - pull: always - ruleset: - event: [ push, pull_request ] -``` - -The caller of this template could look like: - -```yaml -version: "1" -templates: - - name: sample - source: github.com/octocat/hello-world/.vela/build.yml - type: github - -steps: - - name: golang - template: - name: sample - vars: - image: golang:latest -``` diff --git a/content/templates/registry/_index.md b/content/templates/registry/_index.md deleted file mode 100644 index c037ecc69..000000000 --- a/content/templates/registry/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Registry" -linkTitle: "Registry" -description: > - List of community templates to customize Vela pipelines. ---- - -COMING SOON! diff --git a/content/templates/tutorials/_index.md b/content/templates/tutorials/_index.md index 0df425da1..5a9cf6d90 100644 --- a/content/templates/tutorials/_index.md +++ b/content/templates/tutorials/_index.md @@ -4,3 +4,9 @@ linkTitle: "Tutorials" description: > Learn how to write your own templates for Vela. --- + +{{% alert title="Note:" color="primary" %}} +Pipeline templates are an advanced way to write pipelines. We strongly recommend you have a grasp on the following concepts before continuing: + +* [Steps](/docs/concepts/pipeline/steps/) +{{% /alert %}} diff --git a/content/templates/tutorials/go/_index.md b/content/templates/tutorials/go/_index.md new file mode 100644 index 000000000..fae64b676 --- /dev/null +++ b/content/templates/tutorials/go/_index.md @@ -0,0 +1,6 @@ +--- +title: "Go" +linkTitle: "Go" +description: > + See examples on how to write Go templates. +--- diff --git a/content/templates/tutorials/conditional.md b/content/templates/tutorials/go/conditional.md similarity index 94% rename from content/templates/tutorials/conditional.md rename to content/templates/tutorials/go/conditional.md index 57193937e..55c669823 100644 --- a/content/templates/tutorials/conditional.md +++ b/content/templates/tutorials/go/conditional.md @@ -2,7 +2,7 @@ title: "Conditionals" linkTitle: "Conditionals" description: > - Learn how to write a Vela template with conditionals. + Example Go template with conditionals. --- {{% alert color="note" %}} @@ -39,7 +39,7 @@ Let's take a look at using a conditional with a variable in a template: metadata: template: true -{{$br := .branch}} +{{$br := vela "BUILD_BRANCH"}} steps: @@ -76,12 +76,11 @@ templates: steps: - name: golang - template: + template: name: sample vars: image: golang:latest pull_policy: "pull: always" - branch: master ``` Which means the compiled pipeline for execution on a worker is: diff --git a/content/templates/tutorials/loops_maps.md b/content/templates/tutorials/go/loops_maps.md similarity index 97% rename from content/templates/tutorials/loops_maps.md rename to content/templates/tutorials/go/loops_maps.md index 3df8cb370..8332df585 100644 --- a/content/templates/tutorials/loops_maps.md +++ b/content/templates/tutorials/go/loops_maps.md @@ -2,7 +2,7 @@ title: "Loops with Maps" linkTitle: "Loops with Maps" description: > - Learn how to write a Vela template with loops and maps. + Example Go template with loops and maps. --- {{% alert color="note" %}} @@ -77,7 +77,7 @@ templates: steps: - name: golang - template: + template: name: sample vars: pull_policy: "pull: always" diff --git a/content/templates/tutorials/loops_slice.md b/content/templates/tutorials/go/loops_slice.md similarity index 97% rename from content/templates/tutorials/loops_slice.md rename to content/templates/tutorials/go/loops_slice.md index 337d659ab..da8b89141 100644 --- a/content/templates/tutorials/loops_slice.md +++ b/content/templates/tutorials/go/loops_slice.md @@ -2,7 +2,7 @@ title: "Loops with Slices" linkTitle: "Loops with Slices" description: > - Learn how to write a Vela template with loops and slices. + Example Go template with loops and slices. --- {{% alert color="note" %}} diff --git a/content/templates/tutorials/mulitline.md b/content/templates/tutorials/go/mulitline.md similarity index 96% rename from content/templates/tutorials/mulitline.md rename to content/templates/tutorials/go/mulitline.md index 95342ce29..f84b5397e 100644 --- a/content/templates/tutorials/mulitline.md +++ b/content/templates/tutorials/go/mulitline.md @@ -2,7 +2,7 @@ title: "Multiline" linkTitle: "Multiline" description: > - Learn how to write a Vela template that passes multiline strings. + Example Go template with multiline strings. --- {{% alert color="note" %}} diff --git a/content/templates/tutorials/go/vars_platform.md b/content/templates/tutorials/go/vars_platform.md new file mode 100644 index 000000000..710ac5c8d --- /dev/null +++ b/content/templates/tutorials/go/vars_platform.md @@ -0,0 +1,72 @@ +--- +title: "Platform Vars" +linkTitle: "Platform Vars" +description: > + Example Go template with platform vars. +--- + +{{% alert color="note" %}} +We recommend reviewing [Go Templates documentation](https://golang.org/pkg/text/template/) before attempting to create a template. + +If you're new to YAML we also recommend reviewing the [YAML 1.2 spec](https://yaml.org/spec/1.2/spec.html) for validation on syntax. +{{% /alert %}} + +## Overview + +Platform variables can be referenced with the following syntax: + +`{{ vela "" }}` + +## Examples + +- `{{ vela "VELA_FULL_REPO_NAME" }}` equates to the `VELA_FULL_REPO_NAME` environment variable +- `{{ vela "FULL_REPO_NAME" }}` equates to the `VELA_REPO_NAME` environment variable +- `{{ vela "VELA_BUILD_NUMBER" }}` equates to the `VELA_BUILD_NUMBER` environment variable +- `{{ vela "VELA_ADDR" }}` equates to the `VELA_ADDR` environment variable + +## Sample + +Let's take a look at using a platform variable in a template: + +```yaml +metadata: + template: true + +steps: + - name: test + commands: + - echo {{ vela "VELA_REPO_FULL_NAME" }} + image: alpine + pull: always + ruleset: + event: [ push, pull_request ] +``` + +The caller of this template could look like: + +```yaml +version: "1" +templates: + - name: sample + source: github.com///path/to/file/