Generic PullRequest interaction

This Task allows a user to interact with an SCM (source control management) system through an abstracted interface (implemented uisng jenkins-x/go-scm).

• Install the Task
• Configure the Task
• Usage
• PullRequest Image

This Task works with both public SCM instances and self-hosted/enterprise GitHub/GitLab instances. For a GitHub specific Task see github.

Mode: Upload or Download

In download mode, this Task will look at the state of an existing pull request and populate the pr workspace with the state of the pull request, including the .MANIFEST file.

If you want to update or delete existing attributes of a PR, running download first will allow you to use upload to make those changes.

In upload mode, this Task will look at the contents of the pr workspace and compare it to the .MANIFEST file (if it exists). Any differences will result in requests being made to bring the Pull Request into the state described in the workspace.

Install the Tasks

To install the Task:

kubectl apply -f pullrequest/pr.yaml

Configuring the Tasks

Parameters

• mode (Required)- The mode ("upload" or "download")
• url (Required) - The complete URL of the Pull Request, e.g. https://github.com/bobcatfish/catservice/pull/16
• provider (Required) - The type of SCM system, currently github or gitlab
• secret-key-ref (Required) - The name of a secret key containing the token required for SCM requests
• insecure-skip-tls-verify (Default: "false") - If "true", certificate validation will be disabled

Workspaces

The pr workspace holds all the data about any labels, statuses, comments you want to update.

The files in the pr workspace represent the state of the configured PR, i.e. the current state when using download mode and/or the desired state when using upload mode.

The structure of the workspace is:

• /labels/<label> - These are empty files, the name of the file is the name of the label (URL encode non-URL safe characters).
• /status/<status> - These are json files that represent statuses
• /comments/<comment> - These are json files that represent comments
• base.json - Information about the base commit of the PR
• head.json - Information about the head commit of the PR
• pr.json - Information about the PR

When populated via download, the file .MANIFEST is populated and used to represent the current state of the Pull Request; before upload mutates the the Pull Request it will compare the contents of the pr workspace to this file to determine what has changed.

See pr-example for an example of a pr workspace poulated with comments, labels, and statuses (.MANIFEST file not included).

statuses

Each status file is a json file containing a dictionary with the following keys:

• Label: The name of the status
• Desc: (optional) A string to associate with the current state of the status
• Target: (optional) A link to where more information can be found (e.g. link to logs)
• State: The state of the status, valid options are:
  • unknown
  • pending
  • running
  • success
  • failure
  • cancelled
  • expected
  • error

{
  "State": "pending",
  "Label": "pull-tekton-pipeline-build-tests",
  "Desc": "Job triggered.",
  "Target": "https://tekton-releases.appspot.com/build/tekton-prow/pr-logs/pull/tektoncd_pipeline/995/pull-tekton-pipeline-build-tests/1146102490727452672/"
}

See pr-example/status for examples.

comments

The format of the files in comments depends on whether upload or download mode is being used.

pipeline#2168

upload mode comments

When uploading comments, the content of the file is used as the body of the comment.

download mode comments

Each comment file is a json file containing a dictionary that represents a comment in a vendor agnostic way with these keys:

• ID - Identifier of the comment
• Body - Body of the comment
• Link - URL that links to the comment
• Created - ISO 8601 conforming string
• Updated - ISO 8601 conforming string
• Author - Another dictionary representing the user who made the comment with the optional keys
  • Login - User's handle
  • Name - User's name
  • Email - User's email
  • Avatar - Link to user's avatar image
  • Link - Link to user's profile
  • Created - ISO 8601 conforming string
  • Updated - ISO 8601 conforming string

See pr-example/comments for examples of GitHub comments.

Usage

Permissions

The Task will need access to an opaque secret containing a token to use when making requests to the SCM provider (configured via the secret-key-ref param). The secret is expected to contain a key called token which contains the auth token as a base64 encoded string, for example:

apiVersion: v1
kind: Secret
metadata:
  name: github-auth-token
type: Opaque
data:
  token: dG9rZW4=

Running the Task

Example TaskRun that would run this Task in download mode:

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  generateName: some-task-run-
spec:
  taskRef:
  - name: pull-request
  workspaces:
  - name: pr
    persistentVolumeClaim:
      claimName: shared-task-storage
  params:
  - name: mode
    value: download
  - name: url
    value: https://github.com/bobcatfish/catservice/pull/16
  - name: provider
    value: github
  - name: secret-key-ref
    value: some-secret

sample/add-comment.yaml contains an example of a PipelineRun which creates a Pipeline to exercise this Task's upload and download functionality.

To try out the sample (note that it expects the existence of a secret called 'webhook-secret`):

kubectl apply -f pullrequest/sample/static.yaml
kubectl create -f pullrequest/sample/add-comment.yaml

PullRequest Image

This Task was created to have feature parity with the Tekton Pipelines PullRequest PipelineResource and uses the pullrequest-init image which is built and published as part of Tekton Pipeline releases.