add-to-repository.adoc

Enable an existing repository to use ODS Pipeline

This guide explains how you can start to use ODS pipeline for your repository. It is assumed you have read the introduction and have aleady installed ODS pipeline in an OpenShift project.

There are only two required steps:

1. Add ods.yaml

2. Configure Bitbucket webhook

Tip	If your repository was originally provisioned by an ODS quickstarter, you might want to follow the convert an ODS quickstarter based component instructions instead.

Tip	If you want to create an ODS Pipeline-enabled repository from scratch, check out the Cookiecutter based templates in github.com/bix-digital/ods-pipeline-examples.

Add ods.yaml

The following uses an Go application for demonstration purposes, however the general steps apply for any other technology as well. Add an ods.yaml file like the following to the root of the repository:

ods.yaml

pipeline:
  - 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

The task defined in tasks/build.yaml in the ods-pipeline-go repository runs tests and produces a Go binary. If you use another technology, e.g. a Java project using Gradle, exchange the task with one fitting your needs.

(Optionally) Create Dockerfile

If you want to create a container image with the produced Go binary, you can add the ods-pipeline-buildah-package task to the tasks list, like this:

ods.yaml

pipeline:
  - 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

This task assumes the Docker context in the docker directory, and the Dockerfile located inside that folder. Therefore, create a directory docker and place a Dockerfile inside like this one:

Dockerfile

FROM alpine

COPY app app

EXPOSE 8080

CMD ["./app"]

Note	ods-pipeline-go-build produces a binary called app and places it at docker/app so that it can be referenced in the Dockerfile and copied into the image by the ods-pipeline-buildah-package task.

Note	Pay attention to the runAfter configuration in the task list: it ensures that the tasks run sequentially and can use the outputs from the previous task(s).

(Optionally) Create Helm Chart

If you want to deploy the created image, you can add the ods-pipeline-helm-deploy task to the tasks list and configure which Kubernetes namespaces to deploy into, like this:

ods.yaml

pipeline:
  - 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
    - name: deploy
      taskRef:
        resolver: git
        params:
        - { name: url, value: https://github.com/opendevstack/ods-pipeline-helm.git }
        - { name: revision, value: v0.1.0 }
        - { name: pathInRepo, value: tasks/deploy.yaml }
      params:
      - name: namespace
        value: foo-dev
      runAfter:
      - package
      workspaces:
      - name: source
        workspace: shared-workspace

This task requires a Helm chart to be present at /chart. It is recommended to start with the sample chart provided in this repository.

Configure Webhook

The final step is to create a Bitbucket webhook pointing to the ODS pipeline installation. To do this, go to "Repository Settings > Webhooks" and create a new webhook:

• "Name": choose any name you wish, e.g. ods-pipeline

• "URL": enter the URL of the route of your event listener, followed by /bitbucket, e.g. https://ods-pipeline.example.com/bitbucket

• "Secret": enter the value of the secret field in the OpenShift ods-bitbucket-webhook Secret.

Select the "Repository: Push" and "Pull request: Opened" events and save the configuration.

Once both ods.yaml and webhook configuration exist, any push in that repo will trigger the pipeline described in ods.yaml.

Next Steps

Once you have done your first steps, consult the ods.yaml reference and the tasks reference for more information.

For an end-to-end example, have a look at the example project.