Skip to content

Latest commit

 

History

History
229 lines (187 loc) · 10.1 KB

ods-configuration.adoc

File metadata and controls

229 lines (187 loc) · 10.1 KB
Raw

ODS.YAML Reference

Table of Contents

This guide will explain how to configure pipelines for your repositories in an ods.yaml file. The configuration in ods.yaml allows the following top-level fields:

  • pipelines

  • repositories

pipelines

The pipelines field allows to define multiple pipelines. Each pipeline specifies when it is triggered (e.g. when a Git push occurs in a specific branch), and which tasks (e.g. build, package, deploy) to run. Example:

ods.yaml
pipelines:
- triggers:
  - branches: ["main"]
  tasks:
  - name: build
    taskRef:
      resolver: git
      params:
      - { name: url, value: https://github.com/opendevstack/ods-pipeline-go.git }
      - { name: revision, value: v0.1.2 }
      - { name: pathInRepo, value: tasks/build.yaml }
    workspaces:
    - name: source
      workspace: shared-workspace
  - name: package
    taskRef:
      resolver: git
      params:
      - { name: url, value: https://github.com/opendevstack/ods-pipeline-image.git }
      - { name: revision, value: v0.1.0 }
      - { name: pathInRepo, value: tasks/package.yaml }
    runAfter:
    - build
    workspaces:
    - name: source
      workspace: shared-workspace

The pipelines created based on the configuration will have a workspace named shared-workspace available, which is backed by a PVC (named ods-pipeline-<component>) in your namespace.

Configuring pipeline tasks

Normal tasks may be specified under tasks. Each task is a plain Tekton definition. See the Tekton documentation on Adding Tasks to the Pipeline for more information.

The exact name of the task (taskRef.name field) depends on the version of ods-pipeline that is installed in your project. Available tasks for you to use can be found in your OpenShift console UI under "Pipelines > Tasks".

Next to the tasks you specify, ods-pipeline will automatically inject two tasks into the pipeline, ods-start and ods-finish:

  • ods-start is inserted as the very first task, checking out the repository given in the webhook, setting the Bitbucket build status and dealing with Nexus artifacts, etc.

  • ods-finish task is added as a final task to the pipeline. Final tasks run at the end, regardless whether all previous tasks succeeded. The ods-finish sets the Bitbucket build status and deals with Nexus artifacts, etc.

Alternatively to referencing tasks, inline task definitions can also be specified:

ods.yaml
pipelines:
- tasks:
  - name: build
    taskSpec:
      steps:
      - name: message
        image: ubuntu
        script: |
          #!/usr/bin/env bash
          echo "hello world"
          cat README.md # assuming there is a README.md file at the root of the repo
        workingDir: $(workspaces.source.path)
      workspaces:
      - name: source
    workspaces:
    - name: source
      workspace: shared-workspace

Further, if remote resolution is enabled, tasks can also be resolved remotely, e.g. from Git:

ods.yaml
pipelines:
- tasks:
  - name: build
    taskRef:
      resolver: git
      params:
      - { name: url, value: https://github.com/opendevstack/ods-pipeline-go.git }
      - { name: revision, value: v0.1.2 }
      - { name: pathInRepo, value: tasks/build.yaml }
    workspaces:
    - name: source
      workspace: shared-workspace

Configuring final tasks

You can also specify further final tasks to be added to the pipeline by specifying them under finally. Example:

ods.yaml
pipelines:
- tasks: [ ... ]
  finally:
  - name: foo
    taskRef:
      kind: Task
      name: foo
    workspaces:
    - name: source
      workspace: shared-workspace

Note that you cannot configure the execution order of final tasks. Final tasks all run simultaneously. For more information on final tasks, see the Tekton documentation on Adding Finally to the Pipeline.

Configuring pipeline triggers

Using the triggers section, it is possible to narrow down in response to which events the pipeline should run. Further, each trigger can pass individual parameters to the referenced pipeline, allowing to modify the behaviour of the pipeline.

Matching webhook events

Example:

pipelines:
- triggers:
  - events: ["repo:refs_changed", "pr:*"]
    branches: ["feature/*"]
    exceptBranches: ["feature/foo"]
    prComment: "/build"
  tasks: []

The following selection criteria may be specified:

events

List of events that trigger the pipeline. Patterns as supported by path.Match may be used to match events. In case the event property is omitted in ods.yaml, any supported event will trigger the respective pipeline.

branches

List of branches to which the triggering event shall refer. Patterns as supported by path.Match may be used to match branches. Not specifying the branches criterion will match webhook events on any branch in the repository.

exceptBranches

List of branches to which the triggering event may not refer. Patterns as supported by path.Match may be used to match the excluded branches. Omitting the criterion will lead to none of the branches referred to in the webhook event to be excluded.

tags

List of tags to which the triggering event shall refer. Patterns as supported by path.Match may be used to match tags. Not specifying the tags criterion will match webhook events on any tag in the repository.

exceptTags

List of tags to which the triggering event may not refer. Patterns as supported by path.Match may be used to match the excluded tags. Omitting the criterion will lead to none of the tags referred to in the webhook event to be excluded.

prComment

Define a prefix a comment has to start with. Might be used to implement functionality like slash commands. If omitted, comments won’t be considered in the pipeline selection process.

Caution
 path.Match does not match e.g. feature/foo when the pattern is just *. If you want to match strings with slashes, specify the pattern */* as well. For example, to match all branches, write branches: ["*", "*/*"].

Currently, the Bitbucket events repo:refs_changed (fired on push to a Bitbucket repository) and any Pull Request related events (event types with prefix pr:) are supported (for a full list of events, please refer to the Atlassian Bitbucket Documentation). Only the first trigger matching all conditions will be selected. If no trigger section is specified, the pipeline will always match.

Passing parameters

The params field of each trigger can be used to pass parameters to the pipeline and its tasks. This mechanism can be used to pass dynamic parameter values based on the Git ref, for example to deploy into different namespaces depending on the checked out branch.

Example:

ods.yaml
pipelines:
- triggers:
  - branches: ["develop"]
    params:
    - { name: deploy.namespace, value: "foo-dev" }
  - branches: ["production"]
    params:
    - { name: deploy.namespace, value: "foo-prod" }
  tasks:
  - name: deploy
    taskRef:
      kind: Task
      name: my-task
    workspaces:
    - name: source
      workspace: shared-workspace

Parameters when prefixed with <task-name>. are passed to the task named <task-name>. When no prefix is set, the parameter is available as a normal pipeline run parameter.

Configuring other pipeline run aspects

Aside from tasks and finally, you may also specify timeouts, podTemplate and taskRunSpecs for more advanced configuration.

The following example adds an additional environment variable and, if enable-api-fields is set to alpha, overrides compute resources of a remotely resolved task:

ods.yaml
pipelines:
- tasks:
  - name: build
    taskRef:
      resolver: git
        params:
        - { name: url, value: https://github.com/opendevstack/ods-pipeline-go.git }
        - { name: revision, value: v0.1.2 }
        - { name: pathInRepo, value: tasks/build.yaml }
      workspaces:
      - name: source
        workspace: shared-workspace
  taskRunSpecs:
  - pipelineTaskName: build
    podTemplate:
      env:
      - { name: MY_VAR, value: 'my value' }
    computeResources:
      requests:
        memory: 2Gi

repositories

If your application is made out of multiple components, you may want to have one "umbrella" repository that ties all those components together and deploys the whole application together. In this case, the umbrella repository can specify the subrepositories via the repositories field. Example:

ods.yaml
repositories:
- name: foo
  tag: v1.0.0
- name: bar
  branch: main
  url: https://bitbucket.acme.org/scm/baz/bar.git

If the repository does not specify a URL, the repository is assumed to be under the same organisation as the repository hosting the ods.yaml file. If a tag is given, it has precedence over branch. If neither tag nor branch is given, the master branch is used as a default.

Repositories listed in ods.yaml are checked out in ods-pipeline-start in .ods/repos and any tasks in the pipeline can alter their behaviour based on the presence of subrepos. For example, the ods-pipeline-helm-deploy task will package any charts in subrepos and add them to the chart in the umbrella repository, deploying all charts as one release.