Skip to content

Commit

Permalink
Add documentation
Browse files Browse the repository at this point in the history 
Signed-off-by: Chmouel Boudjnah <[email protected]>
  • Loading branch information
@chmouel
chmouel committed Dec 11, 2024
1 parent 3f26707 commit 15a87e1
Show file tree
Hide file tree
Showing 2 changed files with 57 additions and 19 deletions.
35 changes: 18 additions & 17 deletions docs/content/docs/guide/authoringprs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}` | <[email protected]> |
| 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 }}` | <[email protected]> |
| 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

Expand Down
41 changes: 39 additions & 2 deletions docs/content/docs/guide/matchingevents.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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" >}}

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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`.
Expand Down

0 comments on commit 15a87e1

Please sign in to comment.