Add doc for passing arguments to GitOps commands

Add documentation for passing arguments to GitOps commands. We moved all the
documentation in a separate file to make it easier to read and find
since it was becoming too big in the `running.md` file.

Add some unittest as well so to make sure the documentation match the
implementation 🙃

Signed-off-by: Chmouel Boudjnah <[email protected]>

Author: chmouel

docs/content/docs/guide/authoringprs.md

@@ -25,9 +25,27 @@ weight: 3
   [git-clone](https://github.com/tektoncd/catalog/blob/main/task/git-clone/)
   task from the [tektoncd/catalog](https://github.com/tektoncd/catalog).
 
-  To be able to specify the parameters of your commit and URL, Pipelines-as-Code
-  allows you to have those "dynamic" variables expanded. Those variables look
-  like this `{{ var }}` and those are the one you can use:
+- To be able to specify parameters of your commit and URL, Pipelines-as-Code
+  give you some “dynamic” variables that is defined according to the execution
+  of the events. Those variables look like this `{{ var }}` and can be used
+  anywhere in your template, see [below](#dynamic-variables) for the list of
+  available variables.
+
+- For Pipelines-as-Code to process your `PipelineRun`, you must have either an
+  embedded `PipelineSpec` or a separate `Pipeline` object that references a YAML
+  file in the `.tekton` directory. The Pipeline object can include `TaskSpecs`,
+  which may be defined separately as Tasks in another YAML file in the same
+  directory. It's important to give each `PipelineRun` a unique name to avoid
+  conflicts. **PipelineRuns with duplicate names will never be matched**.
+
+## Dynamic variables
+
+Here is a list of al the dynamic variables available in Pipelines-as-Code. The
+one that would be the most important to you would probably be the `revision` and `repo_url`
+variables, they will give you the commit SHA and the repository URL that is
+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               |
 |---------------------|---------------------------------------------------------------------------------------------------|-------------------------------------|------------------------------|
@@ -47,13 +65,6 @@ weight: 3
 | 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             |
 
-- For Pipelines-as-Code to process your `PipelineRun`, you must have either an
-  embedded `PipelineSpec` or a separate `Pipeline` object that references a YAML
-  file in the `.tekton` directory. The Pipeline object can include `TaskSpecs`,
-  which may be defined separately as Tasks in another YAML file in the same
-  directory. It's important to give each `PipelineRun` a unique name to avoid
-  conflicts. **PipelineRuns with duplicate names will never be matched**.
-
 ## Matching an event to a PipelineRun
 
 Each `PipelineRun` can match different Git provider events through some special
@@ -196,13 +207,9 @@ metadata:
 Will match the merge-pr PipelineRun when a comment on a pull request starts
 with `/merge-pr`
 
-You can then use the template variable `{{ trigger_comment }}` to get the
-actual comment and do some action based on for example the comment content.
-There is a restriction with the trigger_comment variable we modify it to
-replace the newline with a `\n` since the multi-line comment can cause a
-issue when replaced inside the yaml. It is up to you to replace it back to
-newline, for example with shell scripts you can use `echo -e` to expand the
-newline back.
+When the PipelineRun that has been triggered with the `on-comment` annotation
+gets started the template variable `{{ trigger_comment }}` get set. See the
+documentation [here]({{< relref "/docs/guide/gitops_commands/#accessing-the-comment-triggering-the-pipelinerun" >}})
 
 Note that the `on-comment` annotation will respect the `pull_request` [Policy]({{< relref "/docs/guide/policy" >}}) rule,
 so only users into the `pull_request` policy will be able to trigger the

docs/content/docs/guide/gitops_commands.md

@@ -0,0 +1,229 @@
+---
+title: Gitops Commands
+weight: 5.1
+---
+# GitOps commands
+
+Pipelines-as-Code support the concept of `GitOps commands` a way to have the
+users issue a special command on a comment of a Pull Request or a Pushed Commit
+to control `Pipelines-as-Code`.
+
+The advantage of using a `Gitops command` is to get a journal of all the
+execution of your Pipeline directly on your Pull request near your code.
+
+## GitOps commands on Pull Requests
+
+For example when you are on a Pull Request you may want to restart all your
+pipelineruns, to do so you can add a comment on your pull request starting with
+`/retest` and all PipelineRuns attached to that pull request will be restarted :
+
+Example :
+
+```text
+Thanks for contributing, This is a much needed bugfix, and we love it ❤️ The
+failure is not with your PR but seems to be an infra issue.
+
+/retest
+```
+
+If you have multiple `PipelineRun` and you want to target a specific
+`PipelineRun` you can use the `/test` and the specific PipelineRun as a comment
+to restart it, example:
+
+```text
+roses are red, violets are blue. pipeline are bound to flake by design.
+
+/test <pipelinerun-name>
+```
+
+## GitOps commands on pushed commits
+
+If you want to trigger a GitOps command on a pushed commit, you can include the
+`GitOps` comments within your commit messages. These comments can be used to
+restart either all pipelines or specific ones. Here's how it works:
+
+For restarting all pipeline runs:
+
+1. Use `/retest` or `/test` within your commit message.
+
+For restarting a specific pipeline run:
+2. Use `/retest <pipelinerun-name>` or `/test <pipelinerun-name>` within your
+commit message. Replace `<pipelinerun-name>` with the specific name of the
+pipeline run you want to restart.
+
+**Note:**
+
+When executing `GitOps` commands on a commit that exists in multiple branches
+within a push request, the branch with the latest commit will be used.
+
+This means:
+
+1. If a user specifies commands like `/retest` or `/test` without any argument
+in a comment on a branch, the test will automatically be performed on the **main** branch.
+
+   Examples :
+   1. `/retest`
+   2. `/test`
+   3. `/retest <pipelinerun-name>`
+   4. `/test <pipelinerun-name>`
+
+2. If the user includes a branch specification such as `/retest branch:test` or
+`/test branch:test`, the test will be executed on the commit where the comment is
+located, with the context of the **test** branch.
+
+   Examples :
+   1. `/retest branch:test`
+   2. `/test branch:test`
+   3. `/retest <pipelinerun-name> branch:test`
+   4. `/test <pipelinerun-name> branch:test`
+
+To issue a `GitOps` comment on a pushed commit you can follow these steps:
+
+1. Go to your repository.
+2. Click on the **Commits** section.
+3. Choose one of the individual **Commit**.
+4. Click on the line number where you want to add a `GitOps` comment, as shown in the image below:
+
+![GitOps Commits For Comments](/images/gitops-comments-on-commit.png)
+
+Please note that this feature is supported for the GitHub provider only.
+
+## GitOps commands on non-matching PipelineRun
+
+The PipelineRun will be restarted regardless of the annotations if the comment
+`/test <pipelinerun-name>` or `/retest <pipelinerun-name>` is used . This let
+you have control of PipelineRuns that gets only triggered by a comment on the
+pull request.
+
+## Accessing the comment triggering the PipelineRun
+
+When you trigger a PipelineRun via a Gitops Command, the template variable `{{
+trigger_comment }}` get set to the actual comment that triggered it.
+
+You can then do some action based on for example the comment content with a
+shell script or others.
+
+There is a restriction with the `trigger_comment` variable, we modify it to
+replace the newline with a `\n` since the multi-line comment can cause a issue
+when replaced inside the yaml.
+
+It is up to you to replace it back with newlines, for example with shell scripts
+you can use `echo -e` to expand the newline back.
+
+Example of a shell script:
+
+```shell
+echo -e "{{ trigger_comment }}" > /tmp/comment
+grep "string" /tmp/comment
+```
+
+## Custom GitOps commands
+
+Using the [on-comment]({{< relref
+"/docs/guide/authoringprs.md#matching-a-pipelinerun-on-a-regexp-in-a-comment"
+>}}) annotation on your `PipelineRun` you can define custom GitOps commands that
+will be triggered by the comments on the pull request.
+
+See the [on-comment]({{< relref
+"/docs/guide/authoringprs.md#matching-a-pipelinerun-on-a-regexp-in-a-comment"
+>}}) guide for more detailed information.
+
+## Cancelling a PipelineRun
+
+You can cancel a running PipelineRun by commenting on the PullRequest.
+
+For example if you want to cancel all your PipelinerRuns you can add a comment starting
+with `/cancel` and all PipelineRun attached to that pull request will be cancelled.
+
+Example :
+
+```text
+It seems the infra is down, so cancelling the pipelineruns.
+
+/cancel
+```
+
+If you have multiple `PipelineRun` and you want to target a specific
+`PipelineRun` you can use the `/cancel` comment with the PipelineRun name
+
+Example :
+
+```text
+roses are red, violets are blue. why to run the pipeline when the infra is down.
+
+/cancel <pipelinerun-name>
+```
+
+On GitHub App the status of the Pipeline will be set to `cancelled`.
+
+![pipelinerun canceled](/images/pr-cancel.png)
+
+### Cancelling the PipelineRun on push request
+
+You can cancel a running PipelineRun by commenting on the commit.
+Here's how you can do it.
+
+Example :
+
+1. Use `/cancel` to cancel all PipeineRuns.
+2. Use `/cancel <pipelinerun-name>` to cancel a specific PipeineRun
+
+**Note:**
+
+When executing `GitOps` comments on a commit that exists in multiple branches
+within a push request, the branch with the latest commit will be used.
+
+This means:
+
+1. If a user specifies commands like `/cancel`
+without any argument in a comment on a branch,
+it will automatically target the **main** branch.
+
+   Examples :
+   1. `/cancel`
+   2. `/cancel <pipelinerun-name>`
+
+2. If the user issues a command like `/cancel branch:test`,
+it will target the commit where the comment was made but use the **test** branch.
+
+   Examples :
+   1. `/cancel branch:test`
+   2. `/cancel <pipelinerun-name> branch:test`
+
+In the GitHub App, the status of the Pipeline will be set to `cancelled`.
+
+![GitOps Commits For Comments For PipelineRun Canceled](/images/gitops-comments-on-commit-cancel.png)
+
+Please note that this feature is supported for the GitHub provider only.
+
+## Passing parameters to GitOps commands as argument
+
+{{< tech_preview "Passing parameters to GitOps commands as argument" >}}
+
+When you issue a GitOps command, you can pass arguments to the command to
+redefine some the [standard]({{< relref "/docs/guide/authoringprs#dynamic-variables" >}})
+standard or [custom parameters]({{< relref "/docs/guide/customparams" >}})
+
+For example you can do:
+
+```text
+/test pipelinerun1 key=value
+```
+
+and the custom parameter `key` if defined as custom parameter will be defined to `value`
+
+If the comment does not start with a `/` it will not be parsed.
+
+You can only override parameters from the standard or when set as custom
+parameters, you cannot pass arbitrary parameters that hasn't been defined
+previously.
+
+You can pass those `key=value` anywhere in your comment and it will be parsed.
+
+There is different format that can get accepted, which let you pass values with space or newlines:
+
+* key=value
+* key="a value"
+* key="another \"value\" defined"
+* key="another
+  value with newline"