From 15a87e171764fd0a69cba8022dd5dcada7ec9526 Mon Sep 17 00:00:00 2001 From: Chmouel Boudjnah Date: Wed, 11 Dec 2024 16:15:51 +0100 Subject: [PATCH] Add documentation Signed-off-by: Chmouel Boudjnah --- docs/content/docs/guide/authoringprs.md | 35 +++++++++---------- docs/content/docs/guide/matchingevents.md | 41 +++++++++++++++++++++-- 2 files changed, 57 insertions(+), 19 deletions(-) diff --git a/docs/content/docs/guide/authoringprs.md b/docs/content/docs/guide/authoringprs.md index e10372433..164578ef9 100644 --- a/docs/content/docs/guide/authoringprs.md +++ b/docs/content/docs/guide/authoringprs.md @@ -47,23 +47,24 @@ getting tested. You usually use this with the [git-clone](https://hub.tekton.dev/tekton/task/git-clone) task to be able to checkout the code that is being tested. -| Variable | Description | Example | Example Output | -|---------------------|---------------------------------------------------------------------------------------------------|-------------------------------------|------------------------------| -| body | The full payload body (see [below](#using-the-body-and-headers-in-a-pipelines-as-code-parameter)) | `{{body.pull_request.user.email }}` | | -| event_type | The event type (eg: `pull_request` or `push`) | `{{event_type}}` | pull_request (see the note for Gitops Comments [here]({{< relref "/docs/guide/gitops_commands.md#event-type-annotation-and-dynamic-variables" >}}) ) | -| git_auth_secret | The secret name auto generated with provider token to check out private repos. | `{{git_auth_secret}}` | pac-gitauth-xkxkx | -| headers | The request headers (see [below](#using-the-body-and-headers-in-a-pipelines-as-code-parameter)) | `{{headers['x-github-event']}}` | push | -| pull_request_number | The pull or merge request number, only defined when we are in a `pull_request` event type. | `{{pull_request_number}}` | 1 | -| repo_name | The repository name. | `{{repo_name}}` | pipelines-as-code | -| repo_owner | The repository owner. | `{{repo_owner}}` | openshift-pipelines | -| repo_url | The repository full URL. | `{{repo_url}}` | https:/github.com/repo/owner | -| revision | The commit full sha revision. | `{{revision}}` | 1234567890abcdef | -| sender | The sender username (or accountid on some providers) of the commit. | `{{sender}}` | johndoe | -| source_branch | The branch name where the event come from. | `{{source_branch}}` | main | -| source_url | The source repository URL from which the event come from (same as `repo_url` for push events). | `{{source_url}}` | https:/github.com/repo/owner | -| target_branch | The branch name on which the event targets (same as `source_branch` for push events). | `{{target_branch}}` | main | -| target_namespace | The target namespace where the Repository has matched and the PipelineRun will be created. | `{{target_namespace}}` | my-namespace | -| trigger_comment | The comment triggering the pipelinerun when using a [GitOps command]({{< relref "/docs/guide/running.md#gitops-command-on-pull-or-merge-request" >}}) (like `/test`, `/retest`) | `{{trigger_comment}}` | /merge-pr branch | +| Variable | Description | Example | Example Output | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| body | The full payload body (see [below](#using-the-body-and-headers-in-a-pipelines-as-code-parameter)) | `{{body.pull_request.user.email }}` | | +| event_type | The event type (eg: `pull_request` or `push`) | `{{event_type}}` | pull_request (see the note for Gitops Comments [here]({{< relref "/docs/guide/gitops_commands.md#event-type-annotation-and-dynamic-variables" >}}) ) | +| git_auth_secret | The secret name auto generated with provider token to check out private repos. | `{{git_auth_secret}}` | pac-gitauth-xkxkx | +| headers | The request headers (see [below](#using-the-body-and-headers-in-a-pipelines-as-code-parameter)) | `{{headers['x-github-event']}}` | push | +| pull_request_number | The pull or merge request number, only defined when we are in a `pull_request` event type. | `{{pull_request_number}}` | 1 | +| repo_name | The repository name. | `{{repo_name}}` | pipelines-as-code | +| repo_owner | The repository owner. | `{{repo_owner}}` | openshift-pipelines | +| repo_url | The repository full URL. | `{{repo_url}}` | https:/github.com/repo/owner | +| revision | The commit full sha revision. | `{{revision}}` | 1234567890abcdef | +| sender | The sender username (or accountid on some providers) of the commit. | `{{sender}}` | johndoe | +| source_branch | The branch name where the event come from. | `{{source_branch}}` | main | +| source_url | The source repository URL from which the event come from (same as `repo_url` for push events). | `{{source_url}}` | https:/github.com/repo/owner | +| target_branch | The branch name on which the event targets (same as `source_branch` for push events). | `{{target_branch}}` | main | +| target_namespace | The target namespace where the Repository has matched and the PipelineRun will be created. | `{{target_namespace}}` | my-namespace | +| trigger_comment | The comment triggering the pipelinerun when using a [GitOps command]({{< relref "/docs/guide/running.md#gitops-command-on-pull-or-merge-request" >}}) (like `/test`, `/retest`) | `{{trigger_comment}}` | /merge-pr branch | +| labels | The labels of the pull request separated by a newline | `{{labels}}` | bugs\nenhancement | ## Matching an event to a PipelineRun diff --git a/docs/content/docs/guide/matchingevents.md b/docs/content/docs/guide/matchingevents.md index f7d5f0a61..5434f2c7f 100644 --- a/docs/content/docs/guide/matchingevents.md +++ b/docs/content/docs/guide/matchingevents.md @@ -176,7 +176,7 @@ and you have a `Pull Request` changing the files `.tekton/pipelinerun.yaml`, `on-path-change-ignore` annotation will ignore the `***.md` and `***.yaml` files. -## Matching a PipelineRun on a regexp in a comment +## Matching a PipelineRun on a Regexp in a comment {{< tech_preview "Matching PipelineRun on regexp in comments" >}} @@ -211,6 +211,43 @@ PipelineRun. > *NOTE*: The `on-comment` annotation is only supported on GitHub, Gitea and GitLab providers +## Matching PipelineRun to a Pull Request labels + +{{< tech_preview "Matching PipelineRun to a Pull-Request label" >}} + +Using the annotation `pipelinesascode.tekton.dev/on-label`, you can match a +PipelineRun to a Pull Request label. For example, if you want to match the +PipelineRun `bugs` whenever a Pull Request has the label `bug` or `defect`, you +can use this annotation: + +```yaml +metadata: + name: match-bugs-or-defect + annotations: + pipelinesascode.tekton.dev/on-label: [bug, defect] +``` + +- The `on-label` annotation respects the `pull_request` [Policy]({{< relref + "/docs/guide/policy" >}}) rules. +- This annotation is currently supported only on GitHub, Gitea, and GitLab + providers. Bitbucket Cloud and Bitbucket Server do not support adding labels + to Pull Requests. +- When you add a label to a Pull Request, the corresponding PipelineRun is + triggered immediately, and no other PipelineRun matching the same Pull Request + will be activated. +- If you update the Pull Request by sending a new commit, the PipelineRun + with a matching `on-label` annotation will be triggered again if the label is + still present. +- You can access the `Pull Request` labels with the [dynamic variable]({{< relref "/docs/guide/authoringprs#dynamic-variables" >}}) `{{ labels }}`. + The labels are separated by a Unix newline `\n`. + For example with a shell script you can do this to print them: + + ```bash + for i in $(echo -e "{{ labels }}");do + echo $i + done + ``` + ## Advanced event matching using CEL If you need to do some advanced matching, `Pipelines-as-Code` supports CEL @@ -366,7 +403,7 @@ or close/open the pull request. {{< /hint >}} -### Matching PipelineRun on request header +### Matching a PipelineRun to a request header You can do some further filtering on the headers as passed by the Git provider with the CEL variable `headers`.