Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

RHDEVDOCS 5979 starting pipeline runs manually and on chatops, support OWNERS fully #75409

Merged
merged 1 commit into from
May 8, 2024
Merged

RHDEVDOCS 5979 starting pipeline runs manually and on chatops, support OWNERS fully #75409

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 72 additions & 28 deletions modules/op-creating-pipeline-run-using-pipelines-as-code.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
= Creating a pipeline run using {pac}

[role="_abstract"]
To run pipelines using {pac}, you can create pipelines definitions or templates as YAML files in the `.tekton/` directory of the repository. You can reference YAML files in other repositories using remote URLs, but pipeline runs are only triggered by events in the repository containing the `.tekton/` directory.
To run pipelines using {pac}, you can create pipeline run definitions or templates as YAML files in the `.tekton/` directory of the repository. You can reference YAML files in other repositories using remote URLs, but pipeline runs are only triggered by events in the repository containing the `.tekton/` directory.

The {pac} resolver bundles the pipeline runs with all tasks as a single pipeline run without external dependencies.

Expand Down Expand Up @@ -34,22 +34,23 @@ You can specify the parameters of your commit and URL by using dynamic, expandab
[discrete]
.Matching an event to a pipeline run

You can match different Git provider events with each pipeline by using special annotations on the pipeline run. If there are multiple pipeline runs matching an event, {pac} runs them in parallel and posts the results to the Git provider as soon a pipeline run finishes.
You can match different Git provider events with each pipeline run by using special annotations on the pipeline run. If there are multiple pipeline runs matching an event, {pac} runs them in parallel and posts the results to the Git provider as soon a pipeline run finishes.

[discrete]
.Matching a pull event to a pipeline run

You can use the following example to match the `pipeline-pr-main` pipeline with a `pull_request` event that targets the `main` branch:
You can use the following example to match the `pipeline-pr-main` pipeline run with a `pull_request` event that targets the `main` branch:

[source,yaml]
----
...
metadata:
name: pipeline-pr-main
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[main]" <1>
pipelinesascode.tekton.dev/on-event: "[pull_request]"
...
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: pipeline-pr-main
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[main]" <1>
pipelinesascode.tekton.dev/on-event: "[pull_request]"
# ...
----
<1> You can specify multiple branches by adding comma-separated entries. For example, `"[main, release-nightly]"`. In addition, you can specify the following:
* Full references to branches such as `"refs/heads/main"`
Expand All @@ -59,23 +60,50 @@ You can use the following example to match the `pipeline-pr-main` pipeline with
[discrete]
.Matching a push event to a pipeline run

You can use the following example to match the `pipeline-push-on-main` pipeline with a `push` event targeting the `refs/heads/main` branch:
You can use the following example to match the `pipeline-push-on-main` pipeline run with a `push` event targeting the `refs/heads/main` branch:

[source,yaml]
----
...
metadata:
name: pipeline-push-on-main
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]" <1>
pipelinesascode.tekton.dev/on-event: "[push]"
...
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: pipeline-push-on-main
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]" <1>
pipelinesascode.tekton.dev/on-event: "[push]"
# ...
----
<1> You can specifiy multiple branches by adding comma-separated entries. For example, `"[main, release-nightly]"`. In addition, you can specify the following:
<1> You can specify multiple branches by adding comma-separated entries. For example, `"[main, release-nightly]"`. In addition, you can specify the following:
* Full references to branches such as `"refs/heads/main"`
* Globs with pattern matching such as `"refs/heads/\*"`
* Tags such as `"refs/tags/1.\*"`

[discrete]
.Matching a comment event to a pipeline run
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we mark it a s TP ?


You can use the following example to match the `pipeline-comment` pipeline run with a comment on a pull request, when the text of the comment matches the `^/merge-pr` regular expression:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@chmouel we also support on-comment for push as well right ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@savitaashture no still waiting this to be merged 🙃 openshift-pipelines/pipelines-as-code#1638 (would not make it for osp1.5 now as there is not enough time to dogfood this)

Copy link

@savitaashture savitaashture May 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah i see its still PR
thats what i remembered somewhere i saw the changes but was not able to recall that pull request 😆


[source,yaml]
----
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: pipeline-comment
annotations:
pipelinesascode.tekton.dev/on-comment: "^/merge-pr"
# ...
----

The pipeline run starts only if the comment author meets one of the following requirements:
mramendi marked this conversation as resolved.
Show resolved Hide resolved

* The author is the owner of the repository.
* The author is a collaborator on the repository.
* The author is a public member on the organization of the repository.
* The comment author is listed in the `approvers` or `reviewers` section of the `OWNERS` file in the root of the repository, as defined in the https://www.kubernetes.dev/docs/guide/owners/[Kubernetes documentation]. {pac} supports the specification for the `OWNERS` and `OWNERS_ALIASES` files. If the `OWNERS` file includes a https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#filters[filters] section, {pac} matches approvers and reviewers only against the `.*` filter.

:FeatureName: Matching a comment event to a pipeline run
include::snippets/technology-preview.adoc[]

[discrete]
.Advanced event matching

Expand All @@ -87,7 +115,11 @@ To use CEL-based filtering with {pac}, consider the following examples of annota
+
[source,yaml]
----
...
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: pipeline-advanced-pr
annotations:
pipelinesascode.tekton.dev/on-cel-expression: |
event == "pull_request" && target_branch == "main" && source_branch == "wip"
...
Expand All @@ -97,31 +129,43 @@ To use CEL-based filtering with {pac}, consider the following examples of annota
+
[source,yaml]
----
...
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: pipeline-advanced-pr-pathchanged
annotations:
pipelinesascode.tekton.dev/on-cel-expression: |
event == "pull_request" && "docs/\*.md".pathChanged() <1>
...
event == "pull_request" && "docs/\*.md".pathChanged() # <1>
# ...
----
<1> Matches all markdown files in the `docs` directory.

* To match all pull requests starting with the title `[DOWNSTREAM]`:
+
[source,yaml]
----
...
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: pipeline-advanced-pr-downstream
annotations:
pipelinesascode.tekton.dev/on-cel-expression: |
event == "pull_request && event_title.startsWith("[DOWNSTREAM]")
...
# ...
----

* To run a pipeline on a `pull_request` event, but skip the `experimental` branch:
+
[source,yaml]
----
...
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: pipeline-advanced-pr-not-experimental
annotations:
pipelinesascode.tekton.dev/on-cel-expression: |
event == "pull_request" && target_branch != experimental"
...
# ...
----

For advanced CEL-based filtering while using {pac}, you can use the following fields and suffix functions:
Expand All @@ -134,7 +178,7 @@ For advanced CEL-based filtering while using {pac}, you can use the following fi

In addition, you can access the full payload as passed by the Git repository provider. Use the `headers` field to access the headers of the payload, for example, `headers['x-github-event']`. Use the `body` field to access the body of the payload, for example, `body.pull_request.state`.

:FeatureName: using the header and body of the payload for CEL-based filtering with {pac}
:FeatureName: Using the header and body of the payload for CEL-based filtering with {pac}
include::snippets/technology-preview.adoc[]

In the following example, the pipeline run starts only if all of the following conditions are true:
Expand Down
19 changes: 15 additions & 4 deletions modules/op-restarting-or-canceling-pipeline-run-using-pipelines-as-code.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@
[id="restarting-or-canceling-pipeline-run-using-pipelines-as-code_{context}"]
= Restarting or canceling a pipeline run using {pac}

You can restart or cancel a pipeline run with no events, such as sending a new commit to your branch or raising a pull request. To restart all pipeline runs, use the *Re-run all checks* feature in the GitHub App.
You can restart or cancel a pipeline run with no events, such as sending a new commit to your branch or raising a pull request. To restart all pipeline runs, use the *Re-run all checks* feature in the GitHub App.

To restart all or specific pipeline runs, use the following comments:

* The `/test` and `/retest` comment restarts all pipeline runs.

* The `/test <pipeline_run_name>` and `/retest <pipeline_run_name>` comment restarts a specific pipeline run.
* The `/test <pipeline_run_name>` and `/retest <pipeline_run_name>` comment starts or restarts a specific pipeline run. You can use this command to start any {pac} pipeline run on the repository, whether or not it was triggered by an event for this pipeline run.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that part is TP,


To cancel all or specific pipeline runs, use the following comments:

Expand All @@ -21,6 +21,17 @@ To cancel all or specific pipeline runs, use the following comments:

The results of the comments are visible under the *Checks* tab of the GitHub App.

The comment starts, restarts, or cancels any pipeline runs only if the comment author meets one of the following requirements:

* The author is the owner of the repository.
* The author is a collaborator on the repository.
* The author is a public member on the organization of the repository.
* The comment author is listed in the `approvers` or `reviewers` section of the `OWNERS` file in the root of the repository, as defined in the https://www.kubernetes.dev/docs/guide/owners/[Kubernetes documentation]. {pac} supports the specification for the `OWNERS` and `OWNERS_ALIASES` files. If the `OWNERS` file includes a https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#filters[filters] section, {pac} matches approvers and reviewers only against the `.*` filter.

:FeatureName: Using a comment to start a pipeline run that does not match an event
include::snippets/technology-preview.adoc[]


.Procedure

* If you target a pull request and you use the GitHub App, go to the *Checks* tab and click *Re-run all checks*.
Expand Down Expand Up @@ -49,11 +60,11 @@ This feature is supported for the GitHub provider only.

.. Click on the line number where you want to add a comment.
+
.Example comment that retests a specific pipeline run
.Example comment that starts or restarts a specific pipeline run
[source]
----
This is a comment inside a commit.
/retest <pipeline_run_name>
/retest example_pipeline_run
----
+
[NOTE]
Expand Down
10 changes: 1 addition & 9 deletions modules/op-running-pipeline-run-using-pipelines-as-code.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,7 @@ In the event of a pull request or a merge request, {pac} also runs pipelines fro
* The author is the owner of the repository.
* The author is a collaborator on the repository.
* The author is a public member on the organization of the repository.
* The pull request author is listed in an `OWNER` file located in the repository root of the `main` branch as defined in the GitHub configuration for the repository. Also, the pull request author is added to either `approvers` or `reviewers` section. For example, if an author is listed in the `approvers` section, then a pull request raised by that author starts the pipeline run.

[source,yaml]
----
...
approvers:
- approved
...
----
* The pull request author is listed in the `approvers` or `reviewers` section of the `OWNERS` file in the root of the repository, as defined in the https://www.kubernetes.dev/docs/guide/owners/[Kubernetes documentation]. {pac} supports the specification for the `OWNERS` and `OWNERS_ALIASES` files. If the `OWNERS` file includes a https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#filters[filters] section, {pac} matches approvers and reviewers only against the `.*` filter.

If the pull request author does not meet the requirements, another user who meets the requirements can comment `/ok-to-test` on the pull request, and start the pipeline run.

Expand Down
2 changes: 1 addition & 1 deletion pac/about-pipelines-as-code.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,6 @@ With {pac}, cluster administrators and users with the required privileges can de
* Git events filtering and a separate pipeline for each event.
* Automatic task resolution in {pipelines-shortname}, including local tasks, Tekton Hub, and remote URLs.
* Retrieval of configurations using GitHub blobs and objects API.
* Access Control List (ACL) over a GitHub organization or using a Prow style `OWNER` file.
* Access Control List (ACL) over a GitHub organization or using a Prow style `OWNERS` file.
* The `tkn pac` CLI plugin for managing bootstrapping and {pac} repositories.
* Support for GitHub App, GitHub Webhook, Bitbucket Server, and Bitbucket Cloud.