From 326a4389b4959d65a43c3018c4e454d99405bb4f Mon Sep 17 00:00:00 2001 From: Chmouel Boudjnah Date: Tue, 7 Jan 2025 16:10:01 +0100 Subject: [PATCH] fix(docs): correct grammar and improve clarity - Corrected grammatical errors in multiple documentation files. - Improved clarity and readability of the content. - Ensured consistency in terminology and formatting. Signed-off-by: Chmouel Boudjnah Co-authored-by: Emil Natan Signed-off-by: Chmouel Boudjnah --- docs/content/dev/_index.md | 114 ++++++------ docs/content/docs/guide/authoringprs.md | 64 +++---- docs/content/docs/guide/cli.md | 86 ++++----- docs/content/docs/guide/customparams.md | 28 +-- docs/content/docs/guide/gitops_commands.md | 183 +++++++------------ docs/content/docs/guide/matchingevents.md | 87 +++++---- docs/content/docs/guide/repositorycrd.md | 45 +++-- docs/content/docs/guide/running.md | 9 +- docs/content/docs/install/getting-started.md | 19 +- 9 files changed, 293 insertions(+), 342 deletions(-) diff --git a/docs/content/dev/_index.md b/docs/content/dev/_index.md index 3354b9379..46c675f99 100644 --- a/docs/content/dev/_index.md +++ b/docs/content/dev/_index.md @@ -16,29 +16,29 @@ It uses kind under docker. You start it with: make dev ``` -When it finished you will have the following installed in your kind cluster: +When it finishes, you will have the following installed in your kind cluster: - Kind Cluster deployment - Internal registry to push to from `ko` -- A ingress controller with nginx for routing. -- Tekton and Dashboard installed with a ingress route. +- An ingress controller with nginx for routing. +- Tekton and Dashboard installed with an ingress route. - Pipelines as code deployed from your repo with ko. -- Gitea service running locally so you can run your E2E tests that targets gitea (the most comprehensive ones) +- Gitea service running locally so you can run the E2E tests against it (Gitea has the most comprehensive set of tests). -By default it will try to install from -$GOPATH/src/github.com/openshift-pipelines/pipelines-as-code, if you want to -override it you can set the `PAC_DIRS` environment variable. +By default, it will try to install from +$GOPATH/src/github.com/openshift-pipelines/pipelines-as-code. To override it, +set the `PAC_DIRS` environment variable. -- It will deploy under the nip.io domain reflector, the URL will be : +- It will deploy under the nip.io domain reflector, the URL will be: - - -- You will need to create secret yourself, if you have the [pass cli](https://www.passwordstore.org/) - installed you can point to a folder which contains : github-application-id github-private-key webhook.secret - As configured from your GitHub application. Configure `PAC_PASS_SECRET_FOLDER` +- You will need to create the secret yourself. If you have the [pass cli](https://www.passwordstore.org/) + installed, you can point to a folder that contains: github-application-id, github-private-key, webhook.secret + as configured from your GitHub application. Set the `PAC_PASS_SECRET_FOLDER` environment variable to point to it. - For example : + For example: ```shell pass insert github-app/github-application-id @@ -46,7 +46,7 @@ override it you can set the `PAC_DIRS` environment variable. pass insert -m github-app/github-private-key ``` -- If you need to redeploy your pac install (and only pac) you can do : +- If you need to redeploy your pac install (and only pac), you can do: ```shell ./hack/dev/kind/install.sh -p @@ -58,16 +58,16 @@ override it you can set the `PAC_DIRS` environment variable. make rdev ``` - or you can do this directly with ko : + or you can do this directly with ko: ```shell env KO_DOCKER_REPO=localhost:5000 ko apply -f ${1:-"config"} -B ``` - more flags: `-b` to only do the kind creation+nginx+docker image, `-r` to - install from latest stable release (override with env variable `PAC_RELEASE`) - instead of ko. `-c` will only do the pac configuration (ie: creation of - secrets/ingress etc..) + install from the latest stable release (override with the env variable `PAC_RELEASE`) + instead of ko. `-c` will only do the pac configuration (i.e., creation of + secrets/ingress, etc..) - see the [install.sh](https://github.com/openshift-pipelines/pipelines-as-code/blob/main/hack/dev/kind/install.sh) -h for all flags @@ -114,8 +114,8 @@ stringData: webhook: "" # make sure it's empty when you set this up on the interface and here ``` -There is some gotchas with the webhook validation secret, Pipelines-as-Code -detect a Gitea install and let the user set a empty webhook secret (by default +There are some gotchas with the webhook validation secret. Pipelines-as-Code +detects a Gitea install and lets the user set an empty webhook secret (by default it's enforced). The `install.sh` script will by default spin up a new instance of GITEA to play @@ -124,26 +124,26 @@ with and run the Gitea E2E tests. You will need to create a Hook URL generated from into the environment variable `TEST_GITEA_SMEEURL`. -The defaults are : +The defaults are: - URL: - Admin Username: pac - Admin Password: pac -The E2E tests will automatically create repo using the admin username for each tests. +The E2E tests will automatically create a repo using the admin username for each test. ## Debugging E2E -As long you have the secrets setup you should be able to run the e2e tests properly. -Gitea are the easiest to run (since they are self contained), for the other you -will need to setup some environment variables. +As long as you have the secrets set up, you should be able to run the e2e tests properly. +Gitea is the easiest to run (since they are self-contained). For the rest, +you will need to set up some environment variables. See the [e2e on kind workflow](https://github.com/openshift-pipelines/pipelines-as-code/blob/8f990bf5f348f6529deaa3693257907b42287a35/.github/workflows/kind-e2e-tests.yaml#L90) -for all the variables set by provider. +for all the variables set by the provider. -By default the E2E tests cleanups after themselves if you want to keep the -PR/MR opens and the namespace where the test has been created you can set the +By default, the E2E tests clean up after themselves. If you want to keep the +PR/MR open and the namespace where the test has been created, you can set the `TEST_NOCLEANUP` environment variable to `true`. ## Debugging controller @@ -154,31 +154,31 @@ to your locally installed controller (this can be either run on your debugger or inside kind). An option of gosmee is to save the replay to a directory with `--saveDir -/tmp/save`. If go to that directory a shell script will be created to replay +/tmp/save`. If you go to that directory, a shell script will be created to replay the request that was sent directly to the controller without having to go through another push. -Use [snazy](https://github.com/chmouel/snazy) to watch the logs, it support pac +Use [snazy](https://github.com/chmouel/snazy) to watch the logs. It supports pac by adding some context like which GitHub provider. ![snazy screenshot](/images/pac-snazy.png) ## Using the Makefile targets -Several target in the Makefile is available, if you need to run them +Several targets are available in the Makefile if you want to run them manually. You can list all the makefile targets with: ```shell make help ``` -For example to test and lint the go files : +For example, to test and lint the go files: ```shell make test lint-go ``` -If you add a CLI command with help you will need to regenerate the golden files : +If you add a CLI command with help, you will need to regenerate the golden files: ```shell make update-golden @@ -190,27 +190,27 @@ We are using several tools to verify that pipelines-as-code is up to a good coding and documentation standard. We use pre-commit tools to ensure before you send your PR that the commit is valid. -First you need to install pre-commit: +First, you need to install pre-commit: -It should be available as package on Fedora and Brew or install it with `pip`. +It should be available as a package on Fedora and Brew or install it with `pip`. -When you have it installed add the hook to your repo by doing : +Once installed, add the hook to your repo by doing: ```shell pre-commit install ``` -This will run several `hooks` on the files that has been changed before you +This will run several `hooks` on the files that have been changed before you _push_ to your remote branch. If you need to skip the verification (for whatever -reason), you can do : +reason), you can do: ```shell git push --no-verify ``` -or you can disable individual hook with the `SKIP` variable: +or you can disable an individual hook with the `SKIP` variable: ```shell SKIP=lint-md git push @@ -240,10 +240,10 @@ generated) and start the Hugo server with a live preview of the docs on: -When we push the release, the docs gets rebuilt automatically by CloudFare pages. +When we push the release, the docs get rebuilt automatically by CloudFare pages. -By default the website only contains the "stable" -documentation. If you want to preview the dev documentation as from `main` you +By default, the website only contains the "stable" +documentation. If you want to preview the dev documentation as from `main`, you need to go to this URL: @@ -259,12 +259,12 @@ major version. ### Go Modules -Unless if we that's not possible we try to update all dependencies to the -latest version as long it's compatible with the Pipeline version as shipped by +Unless that's not possible, we try to update all dependencies to the +latest version as long as it's compatible with the Pipeline version as shipped by OpenShift Pipelines Operator (which should be conservative). -Every time you do a go modules update check if we can remove the `replace` -clause that pins a dependency to a specific version/commit or match the replace +Every time you update the Go modules, check if you can remove the `replace` +clause which pins a dependency to a specific version/commit or match the replace to the tektoncd/pipeline version. - Update all go modules: @@ -274,8 +274,8 @@ to the tektoncd/pipeline version. make vendor ``` -- Go to and note the latest go version for example: v59 -- Open a file that use the go-github library (ie: pkg/provider/github/detect.go) and check the old version, for example: v56 +- Go to and note the latest go version, for example: v59 +- Open a file that uses the go-github library (i.e., pkg/provider/github/detect.go) and check the old version, for example: v56 - Run this sed command: @@ -283,9 +283,9 @@ to the tektoncd/pipeline version. find -name '*.go'|xargs sed -i 's,github.com/google/go-github/v56,github.com/google/go-github/v59,' ``` -- This will update everything, sometime the library ghinstallation is not +- This will update everything. Sometimes the library ghinstallation is not updated with the new version, so you will need to keep the old version kept in -there. For example you will get this kind of error: +there. For example, you will get this kind of error: ```text pkg/provider/github/parse_payload.go:56:33: cannot use &github.InstallationTokenOptions{…} (value of type *"github.com/google/go-github/v59/github".InstallationTokenOptions) as *"github.com/google/go-github/v57/github".InstallationTokenOptions value in assignment @@ -297,10 +297,10 @@ there. For example you will get this kind of error: make allbinaries test lint ``` -- Some structs needs to be updated, some of them are going to fail on - deprecated, so you will need to figure how to update them. Don't be lazy and avoid the - update with a nolint or a pin to a dep you only delay the inevitable until - the problem come back and hit you harder. +- Some structs need to be updated. Some of them are going to fail as + deprecated, so you will need to figure out how to update them. Don't be lazy and avoid the + update with a nolint or a pin to a dep. You only delay the inevitable until + the problem comes back and hits you harder. ### Go version @@ -311,7 +311,7 @@ there. For example you will get this kind of error: docker run golang go version ``` -- If this not the same as what we have in go.mod then you need to update the go.mod version. then you need to update for example here 1.20: +- If this is not the same as what we have in go.mod, then you need to update the go.mod version. Then you need to update, for example, here 1.20: ```shell go mod tidy -go=1.20 @@ -340,7 +340,7 @@ there. For example you will get this kind of error: ## Tools that are useful -Several tools are used on CI and in `pre-commit`, the non exhaustive list you +Several tools are used in CI and `pre-commit`. The non-exhaustive list you need to have on your system: - [golangci-lint](https://github.com/golangci/golangci-lint) - For golang lint @@ -362,8 +362,8 @@ need to have on your system: ## Target architecture -- We target arm64 and amd64, the dogfooding is on arm64, so we need to make -sure that all jobs and docker images used in the .tekton PipelineRuns are built +- We target arm64 and amd64. The dogfooding is on arm64, so we need to ensure +that all jobs and docker images used in the .tekton PipelineRuns are built for arm64. # Links diff --git a/docs/content/docs/guide/authoringprs.md b/docs/content/docs/guide/authoringprs.md index d4bbd5c67..b81576a00 100644 --- a/docs/content/docs/guide/authoringprs.md +++ b/docs/content/docs/guide/authoringprs.md @@ -5,9 +5,9 @@ weight: 3 # Authoring PipelineRuns in `.tekton/` directory -- Pipelines-as-Code will always try to be as close to the tekton template as - possible. Usually you will write your template and save them with a `.yaml` - extension and Pipelines-as-Code will run them. +- Pipelines-as-Code will always try to be as close to the Tekton template as + possible. Usually, you will write your template and save them with a `.yaml` + extension, and Pipelines-as-Code will run them. - The `.tekton` directory must be at the top level of the repo. You can reference YAML files in other repos using remote URLs @@ -16,17 +16,17 @@ weight: 3 the `.tekton` directory. - Using its [resolver](../resolver/) Pipelines-as-Code will try to bundle the - PipelineRun with all its Task as a single PipelineRun with no external + PipelineRun with all its Tasks as a single PipelineRun with no external dependencies. -- Inside your pipeline you need to be able to check out the commit as - received from the webhook by checking it out the repository from that ref. Most of the time +- Inside your pipeline, you need to be able to check out the commit as + received from the webhook by checking out the repository from that ref. Most of the time you want to reuse the [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 parameters of your commit and URL, Pipelines-as-Code - give you some “dynamic” variables that is defined according to the execution + gives you some “dynamic” variables that are 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. @@ -40,30 +40,30 @@ weight: 3 ## Dynamic variables -Here is a list of al the dynamic variables available in Pipelines-as-Code. The +Here is a list of all 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. +check out 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 | +| 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 | +| sender | The sender username (or account ID on some providers) of the commit. | `{{sender}}` | johndoe | +| source_branch | The branch name where the event comes from. | `{{source_branch}}` | main | +| source_url | The source repository URL from which the event comes 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 | +| 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 | | pull_request_labels | The labels of the pull request separated by a newline | `{{pull_request_labels}}` | bugs\nenhancement | ## Matching an event to a PipelineRun @@ -71,7 +71,7 @@ checkout the code that is being tested. Each `PipelineRun` can match different Git provider events through some special annotations on the `PipelineRun`. -For example when you have these metadatas in +For example, when you have these metadata in your `PipelineRun`: ```yaml @@ -82,20 +82,20 @@ annotations: pipelinesascode.tekton.dev/on-event: "[pull_request]" ``` -`Pipelines-as-Code` will match the pipelinerun `pipeline-pr-main` if the Git +`Pipelines-as-Code` will match the PipelineRun `pipeline-pr-main` if the Git provider events target the branch `main` and it's coming from a `[pull_request]` -There is many ways to match an event to a PipelineRun, head over to this patch -[page]({{< relref "/docs/guide/matchingevents.md" >}}) for a more details. +There are many ways to match an event to a PipelineRun, head over to this patch +[page]({{< relref "/docs/guide/matchingevents.md" >}}) for more details. ## Using the body and headers in a Pipelines-as-Code parameter -Pipelines-as-Code let you access the full body and headers of the request as a CEL expression. +Pipelines-as-Code lets you access the full body and headers of the request as a CEL expression. This allows you to go beyond the standard variables and even play with multiple -conditions and variable to output values. +conditions and variables to output values. -For example if you want to get the title of the Pull Request in your PipelineRun you can simply access it like this: +For example, if you want to get the title of the Pull Request in your PipelineRun you can simply access it like this: ```go {{ body.pull_request.title }} @@ -104,7 +104,7 @@ For example if you want to get the title of the Pull Request in your PipelineRun You can then get creative and for example mix the variable inside a python script to evaluate the json. -This task for example is using python and will check the labels on the PR, +This task, for example, is using python and will check the labels on the PR, `exit 0` if it has the label called 'bug' on the pull request or `exit 1` if it doesn't: @@ -125,7 +125,7 @@ taskSpec: exit(1) ``` -The expression are CEL expressions so you can as well make some conditional: +The expressions are CEL expressions so you can as well make some conditional: ```yaml - name: bash @@ -136,11 +136,11 @@ The expression are CEL expressions so you can as well make some conditional: fi ``` -if the PR is open the condition then return `true` and the shell script see this +if the PR is open the condition then returns `true` and the shell script sees this as a valid boolean. -Headers from the payload body can be accessed from the `headers` keyword, note that headers are case sensitive, -for example this will show the GitHub event type for a GitHub event: +Headers from the payload body can be accessed from the `headers` keyword, note that headers are case-sensitive, +for example, this will show the GitHub event type for a GitHub event: ```yaml {{ headers['X-Github-Event'] }} @@ -153,10 +153,10 @@ and then you can do the same conditional or access as described above for the `b You can use the temporary installation token that is generated by Pipelines as Code from the GitHub App to access the GitHub API. -The token value is stored into the temporary git-auth secret as generated for [private +The token value is stored in the temporary git-auth secret as generated for [private repositories](../privaterepo/) in the key `git-provider-token`. -As an example if you want to add a comment to your pull request, you can use the +As an example, if you want to add a comment to your pull request, you can use the [github-add-comment](https://hub.tekton.dev/tekton/task/github-add-comment) task from the [Tekton Hub](https://hub.tekton.dev) using a [pipelines as code annotation](../resolver/#remote-http-url): @@ -187,7 +187,7 @@ tasks: Since we are using the dynamic variables we are able to reuse this on any PullRequest from any repositories. -and for completeness, here is another example how to set the GITHUB_TOKEN +and for completeness, here is another example of how to set the GITHUB_TOKEN environment variable on a task step: ```yaml @@ -202,8 +202,8 @@ env: {{< hint info >}} - On GitHub apps the generated installation token [will be available for 8 hours](https://docs.github.com/en/developers/apps/building-github-apps/refreshing-user-to-server-access-tokens) -- On GitHub apps the token is scoped to the repository the event (payload) come - from unless [configured](/docs/install/settings#pipelines-as-code-configuration-settings) it differently on cluster. +- On GitHub apps the token is scoped to the repository the event (payload) comes + from unless [configured](/docs/install/settings#pipelines-as-code-configuration-settings) differently on the cluster. {{< /hint >}} diff --git a/docs/content/docs/guide/cli.md b/docs/content/docs/guide/cli.md index 19ee18d15..2fe3ab974 100644 --- a/docs/content/docs/guide/cli.md +++ b/docs/content/docs/guide/cli.md @@ -4,16 +4,16 @@ weight: 100 --- # Pipelines-as-Code CLI -Pipelines-as-Code provide a powerful CLI designed to work as a plug-in to the [Tekton CLI (tkn)](https://github.com/tektoncd/cli). +Pipelines-as-Code provides a powerful CLI designed to work as a plug-in to the [Tekton CLI (tkn)](https://github.com/tektoncd/cli). -`tkn pac` allows you to : +`tkn pac` allows you to: * `bootstrap`: quickly bootstrap a Pipelines-as-Code installation. * `create`: create a new Pipelines-as-Code Repository definition. * `delete`: delete an existing Pipelines-as-Code Repository definition. * `generate`: generate a simple pipelinerun to get you started with Pipelines-as-Code. * `list`: list Pipelines-as-Code Repositories. -* `logs`: show the logs of a PipelineRun form a Repository CRD. +* `logs`: show the logs of a PipelineRun from a Repository CRD. * `describe`: describe a Pipelines-as-Code Repository and the runs associated with it. * `resolve`: Resolve a pipelinerun as if it were executed by pipelines as code on service. * `webhook`: Updates webhook secret. @@ -27,27 +27,27 @@ You can grab the latest binary directly for your operating system from the [releases](https://github.com/openshift-pipelines/pipelines-as-code/releases) page. -Available operating systems are : +Available operating systems are: * MacOS - M1 and x86 architecture -* Linux - 64bits - RPM, Debian packages and tarballs. -* Linux - ARM 64bits - RPM, Debian packages and tarballs. +* Linux - 64bits - RPM, Debian packages, and tarballs. +* Linux - ARM 64bits - RPM, Debian packages, and tarballs. * Windows - Arm 64 Bits and x86 architecture. {{< hint info >}} -On windows tkn-pac will look for the kubernetes config in `%USERPROFILE%\.kube\config` on Linux and MacOS it will use the standard $HOME/.kube/config. +On Windows, tkn-pac will look for the Kubernetes config in `%USERPROFILE%\.kube\config`. On Linux and MacOS, it will use the standard $HOME/.kube/config. {{< /hint >}} {{< /tab >}} {{< tab "Homebrew" >}} -tkn pac plug-in is available from HomeBrew as a "Tap", you simply need to run this command to install it : +tkn pac plug-in is available from HomeBrew as a "Tap". You simply need to run this command to install it: ```shell brew install openshift-pipelines/pipelines-as-code/tektoncd-pac ``` -and if you need to upgrade it : +and if you need to upgrade it: ```shell brew upgrade openshift-pipelines/pipelines-as-code/tektoncd-pac @@ -57,7 +57,7 @@ brew upgrade openshift-pipelines/pipelines-as-code/tektoncd-pac {{< /tab >}} {{< tab "Container" >}} -`tkn-pac` is available as a docker container, : +`tkn-pac` is available as a docker container: ```shell # use docker @@ -68,7 +68,7 @@ podman run -e KUBECONFIG=/tmp/kube/config -v ${HOME}/.kube:/tmp/kube \ {{< /tab >}} {{< tab "GO" >}} -If you want to install from the Git repository you can just do : +If you want to install from the Git repository you can just do: ```shell go install github.com/openshift-pipelines/pipelines-as-code/cmd/tkn-pac @@ -79,7 +79,7 @@ go install github.com/openshift-pipelines/pipelines-as-code/cmd/tkn-pac {{< tab "Arch" >}} You can install the `tkn pac` plugin from the [Arch User Repository](https://aur.archlinux.org/packages/tkn-pac/) (AUR) with your -favourite AUR installer like `yay` : +favorite AUR installer like `yay`: ```shell yay -S tkn-pac @@ -106,8 +106,8 @@ will ask you if you want to install (with `kubectl`) the latest stable release. If you add the flag `--nightly` it will install the latest code ci release. -Bootstrap detect the OpenShift Route automatically associated to the Pipelines -as code controller service and uses this as endpoint for the created GitHub +Bootstrap detects the OpenShift Route automatically associated with the Pipelines +as code controller service and uses this as the endpoint for the created GitHub application. You can use the `--route-url` flag to replace the OpenShift Route URL or specify @@ -115,7 +115,7 @@ a custom URL on an [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) in a Kubernetes cluster. -The OpenShift console is automatically detected, on Kubernetes, `tkn-pac` will +The OpenShift console is automatically detected. On Kubernetes, `tkn-pac` will attempt to detect the tekton-dashboard Ingress URL and let you choose to use it as the endpoint for the created GitHub application. @@ -173,7 +173,7 @@ You can specify the flag `--cascade` to optionally delete the attached secrets ### Repository Listing `tkn pac list` -- will list all the Pipelines-as-Code Repositories -definition and display the last or the current status (if its running) of the +definition and display the last or the current status (if it's running) of the PipelineRun associated with it. You can add the option `-A/--all-namespaces` to list all repositories across the @@ -184,8 +184,8 @@ You can select the repositories by labels with the `-l/--selectors` flag. You can choose to display the real time as RFC3339 rather than the relative time with the `--use-realtime` flag. -On modern terminal (ie: OSX Terminal, [iTerm2](https://iterm2.com/), [Windows -Terminal](https://github.com/microsoft/terminal), GNOME-terminal, kitty and so +On modern terminals (ie: OSX Terminal, [iTerm2](https://iterm2.com/), [Windows +Terminal](https://github.com/microsoft/terminal), GNOME-terminal, kitty, and so on...) the links become clickable with control+click or ⌘+click (see the documentation of your terminal for more details) and will open the browser to the console/dashboard URL to see the details of the Pipelinerun associated @@ -203,15 +203,15 @@ definition and the runs associated with it. You can choose to display the real time as RFC3339 rather than the relative time with the `--use-realtime` flag. -When the last PipelineRun has failure it will print the last 10 lines of every -tasks associated with the PipelineRun thas has been failed highlightign the +When the last PipelineRun has a failure it will print the last 10 lines of every +task associated with the PipelineRun that has failed highlighting the `ERROR` or `FAILURE` and other patterns. -If you want to show the failures of another PipelineRun rather than the last +If you want to show the failures of another PipelineRun rather than the last one you can use the `--target-pipelinerun` or `-t` flag for that. -On modern terminal (ie: OSX Terminal, [iTerm2](https://iterm2.com/), [Windows -Terminal](https://github.com/microsoft/terminal), GNOME-terminal, kitty and so +On modern terminals (ie: OSX Terminal, [iTerm2](https://iterm2.com/), [Windows +Terminal](https://github.com/microsoft/terminal), GNOME-terminal, kitty, and so on...) the links become clickable with control+click or ⌘+click (see the documentation of your terminal for more details) and will open the browser to the console/dashboard URL to see the details of the Pipelinerun associated @@ -226,10 +226,10 @@ with it. `tkn pac logs` -- will show the logs attached to a Repository. If you don't specify a repository on the command line it will ask you to choose -one or auto select it if there is only one. +one or auto-select it if there is only one. -If there is multiple PipelineRuns attached to the Repo it will ask you to choose -one or auto select it if there is only one. +If there are multiple PipelineRuns attached to the Repo it will ask you to choose +one or auto-select it if there is only one. If you add the `-w` flag it will open the console or the dashboard URL to the log. @@ -245,8 +245,8 @@ the logs. Pipelines-as-Code. It will try to be as smart as possible by detecting the current Git information if you run the command from your source code. -It has some basic language detection and add extra task depending on the -language. For example if it detects a file named `setup.py` at the repository +It has some basic language detection and adds extra tasks depending on the +language. For example, if it detects a file named `setup.py` at the repository root it will add the [pylint task](https://hub.tekton.dev/tekton/task/pylint) to the generated pipelinerun. {{< /details >}} @@ -258,14 +258,14 @@ the generated pipelinerun. `tkn-pac resolve`: will run a pipelinerun as if it were executed by pipelines as code on service. -For example if you have a pipelinerun in the `.tekton/pull-request.yaml` file +For example, if you have a pipelinerun in the `.tekton/pull-request.yaml` file you can run the command `tkn-pac resolve` to see it running: ```yaml tkn pac resolve -f .tekton/pull-request.yaml -o /tmp/pull-request-resolved.yaml && kubectl create -f /tmp/pull-request-resolved.yaml ``` -Combined with a kubernetes install running on your local machine (like[Code +Combined with a Kubernetes install running on your local machine (like[Code Ready Containers](https://developers.redhat.com/products/codeready-containers/overview) or [Kubernetes Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) ) you can @@ -277,22 +277,22 @@ Git repository. You can override the parameters with the `-p` flag. -For example if you want to use a Git branch as revision and another repo name -than the current repo name you can just use : +For example, if you want to use a Git branch as a revision and another repo name +than the current repo name you can just use: `tkn pac resolve -f .tekton/pr.yaml -p revision=main -p repo_name=othername` `-f` can as well accept a directory path rather than just a filename and grab -every `yaml` or `yml` files from that directory. +every `yaml` or `yml` file from that directory. Multiple `-f` arguments are accepted to provide multiple files on the command line. -You need to verify that `git-clone` task (if you use it) can access the -repository to the SHA. Which mean if you test your current source code you need +You need to verify that the `git-clone` task (if you use it) can access the +repository to the SHA. Which means if you test your current source code you need to push it first before using `tkn pac resolve|kubectl create -`. Compared with running directly on CI, you need to explicitly specify the list of -filenames or directory where you have the templates. +filenames or directories where you have the templates. On certain clusters, the conversion from v1beta1 to v1 in Tekton may not function correctly, leading to errors when applying the resolved PipelineRun on @@ -311,7 +311,7 @@ You can explicitly provide a token on the command line with the `-t` or `--providerToken` flag, or you can set the environment variable `PAC_PROVIDER_TOKEN` and it will use it instead of asking you. -With the `--no-secret` flag you can completely skip any secret generation. +With the `--no-secret` flag, you can completely skip any secret generation. There is no clean-up of the secret after the run. @@ -319,9 +319,9 @@ There is no clean-up of the secret after the run. {{< details "tkn pac webhook add" >}} -### Configure and create webhook secret for GitHub, GitLab and Bitbucket Cloud provider +### Configure and create webhook secret for GitHub, GitLab, and Bitbucket Cloud provider -`tkn-pac webhook add [-n namespace]`: Allows you to add new webhook secret for a given provider and update the value of the new webhook secret in the existing `Secret` object used to interact with Pipelines-as-Code +`tkn-pac webhook add [-n namespace]`: Allows you to add a new webhook secret for a given provider and update the value of the new webhook secret in the existing `Secret` object used to interact with Pipelines-as-Code {{< /details >}} @@ -329,7 +329,7 @@ There is no clean-up of the secret after the run. ### Update provider token for existing webhook -`tkn pac webhook update-token [-n namespace]`: Allows you to update provider token for an existing `Secret` object to interact with Pipelines-as-Code. +`tkn pac webhook update-token [-n namespace]`: Allows you to update the provider token for an existing `Secret` object to interact with Pipelines-as-Code. {{< /details >}} @@ -365,7 +365,7 @@ GitHub API, but you can specify a custom GitHub API URL using the The `tkn pac info globbing` command allows you to test glob patterns to see if they match, for example, when using the `on-patch-change` annotation. -Here how it works, this example: +Here is how it works, this example: ```bash tkn pac info globbing 'docs/***/*.md' @@ -381,11 +381,11 @@ The first argument is the glob pattern to test (you will be prompted for it if you don't provide one) as specified by the [glob library](https://github.com/gobwas/glob?tab=readme-ov-file#example). -If you want to test against a string to test other annotation that uses globbing +If you want to test against a string to test other annotations that use globbing patterns (like `on-target-branch` annotation) you can use the `-s` or `--string` flag. -For example this will test if the globbing expression `refs/heads/*` matches +For example, this will test if the globbing expression `refs/heads/*` matches `refs/heads/main`: ```bash diff --git a/docs/content/docs/guide/customparams.md b/docs/content/docs/guide/customparams.md index a9ce6a883..fc1ff8d61 100644 --- a/docs/content/docs/guide/customparams.md +++ b/docs/content/docs/guide/customparams.md @@ -4,10 +4,10 @@ weight: 50 --- ## Custom Parameters -Using the `{{ param }}` syntax, Pipelines-as-Code let you expand a variable or +Using the `{{ param }}` syntax, Pipelines-as-Code lets you expand a variable or the payload body inside a template within your PipelineRun. -By default, there are several variables exposed according to the event. To view +By default, several variables are exposed according to the event. To view all the variables exposed by default, refer to the documentation on [Authoring PipelineRuns](../authoringprs#default-parameters). @@ -20,7 +20,7 @@ preferable approach, and custom params expansion should only be used in specific scenarios where Tekton params cannot be used. {{< /hint >}} -As an example here is a custom variable in the Repository CR `spec`: +As an example, here is a custom variable in the Repository CR `spec`: ```yaml spec: @@ -48,16 +48,16 @@ spec: {{< hint info >}} - If you have a `value` and a `secret_ref` defined, the `value` will be used. -- If you don't have a `value` or a `secret_ref` the parameter will not be - parsed, it will be shown as `{{ param }}` in the `PipelineRun`. -- If you don't have a `name` in the `params` the parameter will not parsed. -- If you have multiple `params` with the same `name` the last one will be used. +- If you don't have a `value` or a `secret_ref`, the parameter will not be + parsed, and it will be shown as `{{ param }}` in the `PipelineRun`. +- If you don't have a `name` in the `params`, the parameter will not be parsed. +- If you have multiple `params` with the same `name`, the last one will be used. {{< /hint >}} ### CEL filtering on custom parameters You can define a `param` to only apply the custom parameters expansion when some -conditions has been matched on a `filter`: +conditions have been matched on a `filter`: ```yaml spec: @@ -69,12 +69,12 @@ spec: The `pac` prefix contains all the values as set by default in the templates variables. Refer to the [Authoring PipelineRuns](../authoringprs) documentation -for all the variable exposed by default. +for all the variables exposed by default. The body of the payload is exposed inside the `body` prefix. -For example if you are running a Pull Request on GitHub pac will receive a -payload which has this kind of json: +For example, if you are running a Pull Request on GitHub, pac will receive a +payload that has this kind of JSON: ```json { @@ -98,9 +98,9 @@ The payload of the event contains much more information that can be used with the CEL filter. To see the specific payload content for your provider, refer to the API documentation -You can have multiple `params` with the same name and different filters, the -first param that matches the filter will be picked up. This let you have -different output according to different event, and for example combine a push +You can have multiple `params` with the same name and different filters; the +first param that matches the filter will be picked up. This lets you have +different output according to different events, and for example, combine a push and a pull request event. {{< hint info >}} diff --git a/docs/content/docs/guide/gitops_commands.md b/docs/content/docs/guide/gitops_commands.md index 58c22c0be..a121dd9fb 100644 --- a/docs/content/docs/guide/gitops_commands.md +++ b/docs/content/docs/guide/gitops_commands.md @@ -1,83 +1,68 @@ --- -title: Gitops Commands +title: GitOps Commands weight: 5.1 --- -# GitOps commands +# 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`. +Pipelines-as-Code supports the concept of `GitOps commands`, which allow users to issue special commands in a comment on 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. +The advantage of using a `GitOps command` is that it provides a journal of all the executions of your pipeline directly on your Pull Request, near your code. -## GitOps commands on Pull Requests +## 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 : +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 : +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. +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 infrastructure 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: +If you have multiple `PipelineRun` and you want to target a specific `PipelineRun`, you can use the `/test` command followed by the specific PipelineRun name to restart it. Example: ```text -roses are red, violets are blue. pipeline are bound to flake by design. +Roses are red, violets are blue. Pipelines are bound to flake by design. /test ``` -## GitOps commands on pushed commits +## 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: +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 ` or `/test ` within your -commit message. Replace `` with the specific name of the -pipeline run you want to restart. +2. Use `/retest ` or `/test ` within your commit message. Replace `` 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. +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. +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 : + Examples: 1. `/retest` 2. `/test` 3. `/retest ` 4. `/test ` -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. +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 : + Examples: 1. `/retest branch:test` 2. `/test branch:test` 3. `/retest branch:test` 4. `/test branch:test` -To issue a `GitOps` comment on a pushed commit you can follow these steps: +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. @@ -88,27 +73,19 @@ To issue a `GitOps` comment on a pushed commit you can follow these steps: Please note that this feature is supported for the GitHub provider only. -## GitOps commands on non-matching PipelineRun +## GitOps Commands on Non-Matching PipelineRun -The PipelineRun will be restarted regardless of the annotations if the comment -`/test ` or `/retest ` is used . This let -you have control of PipelineRuns that gets only triggered by a comment on the -pull request. +The PipelineRun will be restarted regardless of the annotations if the comment `/test ` or `/retest ` is used. This allows you to have control of PipelineRuns that get only triggered by a comment on the Pull Request. -## Accessing the comment triggering the PipelineRun +## 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. +When you trigger a PipelineRun via a GitOps Command, the template variable `{{ trigger_comment }}` is 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. +You can then perform actions based on the comment content with a shell script or other methods. -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. +There is a restriction with the `trigger_comment` variable: we modify it to replace newlines with `\n` since multi-line comments can cause issues 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. +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: @@ -117,76 +94,64 @@ echo -e "{{ trigger_comment }}" > /tmp/comment grep "string" /tmp/comment ``` -## Custom GitOps commands +## Custom GitOps Commands -Using the [on-comment]({{< relref -"/docs/guide/matchingevents.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. +Using the [on-comment]({{< relref "/docs/guide/matchingevents.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 comments on the Pull Request. -See the [on-comment]({{< relref -"/docs/guide/matchingevents.md#matching-a-pipelinerun-on-a-regexp-in-a-comment" ->}}) guide for more detailed information. +See the [on-comment]({{< relref "/docs/guide/matchingevents.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. +You can cancel a running PipelineRun by commenting on the Pull Request. -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. +For example, if you want to cancel all your PipelineRuns, you can add a comment starting with `/cancel`, and all PipelineRuns attached to that Pull Request will be cancelled. -Example : +Example: ```text -It seems the infra is down, so cancelling the pipelineruns. +It seems the infrastructure 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 +If you have multiple `PipelineRun` and you want to target a specific `PipelineRun`, you can use the `/cancel` comment with the PipelineRun name. -Example : +Example: ```text -roses are red, violets are blue. why to run the pipeline when the infra is down. +Roses are red, violets are blue. Why run the pipeline when the infrastructure is down. /cancel ``` -On GitHub App the status of the Pipeline will be set to `cancelled`. +In the GitHub App, the status of the Pipeline will be set to `cancelled`. -![pipelinerun canceled](/images/pr-cancel.png) +![PipelineRun Canceled](/images/pr-cancel.png) -### Cancelling the PipelineRun on push request +### Cancelling the PipelineRun on Push Request -You can cancel a running PipelineRun by commenting on the commit. -Here's how you can do it. +You can cancel a running PipelineRun by commenting on the commit. Here's how you can do it. -Example : +Example: -1. Use `/cancel` to cancel all PipeineRuns. -2. Use `/cancel ` to cancel a specific PipeineRun +1. Use `/cancel` to cancel all PipelineRuns. +2. Use `/cancel ` to cancel a specific PipelineRun. **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. +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. +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 : + Examples: 1. `/cancel` 2. `/cancel ` -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. +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 : + Examples: 1. `/cancel branch:test` 2. `/cancel branch:test` @@ -196,31 +161,27 @@ In the GitHub App, the status of the Pipeline will be set to `cancelled`. Please note that this feature is supported for the GitHub provider only. -## Passing parameters to GitOps commands as argument +## Passing Parameters to GitOps Commands as Arguments -{{< tech_preview "Passing parameters to GitOps commands as argument" >}} +{{< tech_preview "Passing parameters to GitOps commands as arguments" >}} -When you issue a GitOps command, you can pass arguments to the command to -redefine some the [standard]({{< relref "/docs/guide/authoringprs#dynamic-variables" >}}) -dynamic variables or the [custom parameters]({{< relref "/docs/guide/customparams" >}}) +When you issue a GitOps command, you can pass arguments to the command to redefine some of the [standard]({{< relref "/docs/guide/authoringprs#dynamic-variables" >}}) dynamic variables or the [custom parameters]({{< relref "/docs/guide/customparams" >}}). -For example you can do: +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` +and the custom parameter `key`, if defined as a custom parameter, will be set to `value`. -If the comment does not start with a `/` it will not be parsed. +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 only override parameters from the standard or when set as custom parameters; you cannot pass arbitrary parameters that haven't been defined previously. -You can pass those `key=value` anywhere in your comment and it will be parsed. +You can pass those `key=value` pairs anywhere in your comment, and they will be parsed. -There is different format that can get accepted, which let you pass values with space or newlines: +There are different formats that can be accepted, allowing you to pass values with spaces or newlines: * key=value * key="a value" @@ -228,21 +189,20 @@ There is different format that can get accepted, which let you pass values with * key="another value with newline" -## Event Type Annotation and dynamic variables +## Event Type Annotation and Dynamic Variables -The `pipeline.tekton.dev/event-type` annotation indicates the type of GitOps -command that has triggered the PipelineRun. +The `pipeline.tekton.dev/event-type` annotation indicates the type of GitOps command that has triggered the PipelineRun. Here are the possible event types: -* `test-all-comment` : The event is a single `/test` that would test every matched pipelinerun. -* `test-comment` : The event is a `/test ` comment that would test a specific PipelineRun. -* `retest-all-comment` : The event is a single `/retest` that would retest every matched pipelinerun. -* `retest-comment` : The event is a `/retest ` that would retest a specific PipelineRun. -* `on-comment`: The event is coming from a custom comment that would trigger a PipelineRun. -* `cancel-all-comment` : The event is a single `/cancel` that would cancel every matched pipelinerun. -* `cancel-comment` : The event is a `/cancel ` that would cancel a specific PipelineRun. -* `ok-to-test-comment` : The event is a `/ok-to-test` that would allow running the CI for a unauthorized user. +* `test-all-comment`: The event is a single `/test` that would test every matched PipelineRun. +* `test-comment`: The event is a `/test ` comment that would test a specific PipelineRun. +* `retest-all-comment`: The event is a single `/retest` that would retest every matched PipelineRun. +* `retest-comment`: The event is a `/retest ` that would retest a specific PipelineRun. +* `on-comment`: The event is coming from a custom comment that would trigger a PipelineRun. +* `cancel-all-comment`: The event is a single `/cancel` that would cancel every matched PipelineRun. +* `cancel-comment`: The event is a `/cancel ` that would cancel a specific PipelineRun. +* `ok-to-test-comment`: The event is a `/ok-to-test` that would allow running the CI for an unauthorized user. When using the `{{ event_type }}` [dynamic variable]({{< relref "/docs/guide/authoringprs.md#dynamic-variables" >}}) for the following event types: @@ -253,9 +213,6 @@ When using the `{{ event_type }}` [dynamic variable]({{< relref "/docs/guide/aut * `cancel-all-comment` * `ok-to-test-comment` -The dynamic variable will return `pull_request` as the event type instead of the specific -categorized GitOps command type. This is to handle backward compatibility with -previous release for users relying on this dynamic variable. +The dynamic variable will return `pull_request` as the event type instead of the specific categorized GitOps command type. This is to handle backward compatibility with previous releases for users relying on this dynamic variable. -This currently only issue a warning in the repository matched namespace but then deprecated and changed to return -the specific event type. +This currently only issues a warning in the repository matched namespace but will then be deprecated and changed to return the specific event type. diff --git a/docs/content/docs/guide/matchingevents.md b/docs/content/docs/guide/matchingevents.md index 77af2c790..991515ea6 100644 --- a/docs/content/docs/guide/matchingevents.md +++ b/docs/content/docs/guide/matchingevents.md @@ -8,7 +8,7 @@ weight: 3 A `PipelineRun` can be matched to a Git provider event by using specific annotations in the `PipelineRun` metadata. -For example when you have these metadata in your `PipelineRun`: +For example, when you have these as metadata in your `PipelineRun`: ```yaml metadata: @@ -18,7 +18,7 @@ annotations: pipelinesascode.tekton.dev/on-event: "[pull_request]" ``` -`Pipelines-as-Code` will match the pipelinerun `pipeline-pr-main` if the Git +`Pipelines-as-Code` will match the PipelineRun `pipeline-pr-main` if the Git provider events target the branch `main` and it's coming from a `[pull_request]` Multiple target branches can be specified, separated by commas, e.g.: @@ -27,11 +27,11 @@ Multiple target branches can be specified, separated by commas, e.g.: pipelinesascode.tekton.dev/on-target-branch: [main, release-nightly] ``` -You can match on `pull_request` events as above, and you can as well match -pipelineRuns on `push` events to a repository +You can match on `pull_request` events as above, and you can also match +PipelineRuns on `push` events to a repository. -For example this will match the pipeline when there is a push to a commit in the -`main` branch : +For example, this will match the pipeline when there is a push to a commit in the +`main` branch: ```yaml metadata: @@ -41,11 +41,11 @@ metadata: pipelinesascode.tekton.dev/on-event: "[push]" ``` -You can specify the full refs like `refs/heads/main` or the shortref like -`main`. You can also specify globs, for example `refs/heads/*` will match any +You can specify the full refs like `refs/heads/main` or the short ref like +`main`. You can also specify globs, for example, `refs/heads/*` will match any target branch or `refs/tags/1.*` will match all the tags starting from `1.`. -A full example for a push of a tag : +A full example for a push of a tag: ```yaml metadata: @@ -58,12 +58,11 @@ annotations: This will match the pipeline `pipeline-push-on-1.0-tags` when you push the 1.0 tags into your repository. -Matching annotations are currently required; otherwise `Pipelines-as-Code` will not +Matching annotations are currently required; otherwise, `Pipelines-as-Code` will not match your `PipelineRun`. -If there are multiple pipelinerun matching an event, it will run all of them in -parallel and posting the results to the provider as soon the PipelineRun -finishes. +When multiple PipelineRuns match an event, it will run them in parallel +and post the results to the provider as soon as the PipelineRun finishes. {{< hint info >}} Payload matching only occurs for events that `Pipelines-as-Code` supports, such as @@ -79,12 +78,12 @@ annotation `pipelinesascode.tekton.dev/on-path-change`. Multiple paths can be specified, separated by commas. The first glob matching the files changes in the PR will trigger the `PipelineRun`. If you want to match -a file or path that has a comma you can html escape it with the `,` html +a file or path that has a comma, you can HTML escape it with the `,` HTML entity. You still need to specify the event type and target branch. If you have a [CEL expression](#matching-pipelinerun-by-path-change) the `on-path-change` -annotation will be ignored +annotation will be ignored. Example: @@ -104,7 +103,7 @@ its subdirectories) or files with a `.rst` suffix in the `manual` directory. {{< hint info >}} The patterns used are [glob](https://en.wikipedia.org/wiki/Glob_(programming)) -patterns, not regexp. Here are some +patterns, not regex. Here are some [examples](https://github.com/gobwas/glob?tab=readme-ov-file#example) from the library used for matching. @@ -129,7 +128,7 @@ a `PipelineRun` when the specified paths have not changed. You still need to specify the event type and target branch. If you have a [CEL expression](#matching-pipelinerun-by-path-change) the `on-path-change-ignore` -annotation will be ignored +annotation will be ignored. This PipelineRun will run when there are changes outside the docs folder: @@ -160,7 +159,7 @@ This configuration triggers the `PipelineRun` when there are changes in the `docs` directory but not in the `docs/generated` directory. The `on-path-change-ignore` annotation will always take precedence over the -`on-path-change` annotation, It means if you have these annotations: +`on-path-change` annotation. It means if you have these annotations: ```yaml metadata: @@ -184,7 +183,7 @@ You can match a PipelineRun on a comment on a Pull Request with the annotation `pipelinesascode.tekton.dev/on-comment`. The comment is a regexp and if a newly created comment has this regexp it will -automatically match the PipelineRun and starts it. +automatically match the PipelineRun and start it. For example: @@ -202,14 +201,14 @@ This will match the merge-pr `PipelineRun` when a comment on a pull request starts with `/merge-pr`. When the PipelineRun that has been triggered with the `on-comment` annotation -gets started the template variable `{{ trigger_comment }}` get set. See the +gets started, the template variable `{{ trigger_comment }}` gets set. See the documentation [here]({{< relref "/docs/guide/gitops_commands.md#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 +so only users in the `pull_request` policy will be able to trigger the PipelineRun. -> *NOTE*: The `on-comment` annotation is only supported on GitHub, Gitea and GitLab providers +> *NOTE*: The `on-comment` annotation is only supported on GitHub, Gitea, and GitLab providers ## Matching PipelineRun to a Pull Request labels @@ -242,7 +241,7 @@ metadata: - You can access the `Pull Request` labels with the [dynamic variable]({{< relref "/docs/guide/authoringprs#dynamic-variables" >}}) `{{ pull_request_labels }}`. The labels are separated by a Unix newline `\n`. - For example with a shell script you can do this to print them: + For example, with a shell script, you can do this to print them: ```bash for i in $(echo -e "{{ pull_request_labels }}");do @@ -253,7 +252,7 @@ metadata: ## Advanced event matching using CEL If you need to do some advanced matching, `Pipelines-as-Code` supports CEL -expression to do advanced filtering on the specific event you need to be matched. +expressions to do advanced filtering on the specific event you need to be matched. If you have the `pipelinesascode.tekton.dev/on-cel-expression` annotation in your PipelineRun, the CEL expression will be used and the `on-target-branch` or @@ -267,7 +266,7 @@ pipelinesascode.tekton.dev/on-cel-expression: | event == "pull_request" && target_branch == "main" && source_branch == "wip" ``` -The fields available are : +The fields available are: | **Field** | **Description** | |-------------------|----------------------------------------------------------------------------------------------------------------------------------| @@ -282,10 +281,10 @@ The fields available are : | `.pathChanged` | A suffix function to a string that can be a glob of a path to check if changed. (Supported only for `GitHub` and `Gitlab` providers.) | | `files` | The list of files that changed in the event (`all`, `added`, `deleted`, `modified`, and `renamed`). Example: `files.all` or `files.deleted`. For pull requests, every file belonging to the pull request will be listed. | -CEL expressions lets you do more complex filtering compared to the simple `on-target` annotation matching and enable more advanced scenarios. +CEL expressions let you do more complex filtering compared to the simple `on-target` annotation matching and enable more advanced scenarios. -For example if I want to have a `PipelineRun` targeting a `pull_request` but -not the `experimental` branch you could have : +For example, if I want to have a `PipelineRun` targeting a `pull_request` but +not the `experimental` branch you could have: ```yaml pipelinesascode.tekton.dev/on-cel-expression: | @@ -293,7 +292,7 @@ pipelinesascode.tekton.dev/on-cel-expression: | ``` {{< hint info >}} -You can find more information about the CEL language spec here : +You can find more information about the CEL language spec here: {{< /hint >}} @@ -301,7 +300,7 @@ You can find more information about the CEL language spec here : ### Matching a PipelineRun to a branch with a regexp In a CEL expression, you can match a field name using a regular expression. For -example if you want to trigger a `PipelineRun` for the`pull_request` event and +example, if you want to trigger a `PipelineRun` for the`pull_request` event and the `source_branch` name containing the substring `feat/`. you can use the following expression: @@ -318,15 +317,15 @@ pattern](https://github.com/gobwas/glob#example) and does not support different If you want to have a PipelineRun running only if a path has changed you can use the `.pathChanged` suffix function with a [glob pattern](https://github.com/gobwas/glob#example). Here -is a concrete example matching every markdown files (as files who has the `.md` -suffix) in the `docs` directory : +is a concrete example matching every markdown file (as files that have the `.md` +suffix) in the `docs` directory: ```yaml pipelinesascode.tekton.dev/on-cel-expression: | event == "pull_request" && "docs/*.md".pathChanged() ``` -This example will match any changed file (added, modified, removed or renamed) that was in the `tmp` directory: +This example will match any changed file (added, modified, removed, or renamed) that was in the `tmp` directory: ```yaml pipelinesascode.tekton.dev/on-cel-expression: | @@ -347,9 +346,9 @@ This example will match modified files with the name of test.go: files.modified.exists(x, x.matches('test.go')) ``` -### Matching PipelineRun to a event (commit, pull_request) title +### Matching PipelineRun to an event (commit, pull_request) title -This example will match all pull request starting with the title `[DOWNSTREAM]`: +This example will match all pull requests starting with the title `[DOWNSTREAM]`: ```yaml pipelinesascode.tekton.dev/on-cel-expression: | @@ -357,7 +356,7 @@ pipelinesascode.tekton.dev/on-cel-expression: | ``` The event title will be the pull request title on `pull_request` and the -commit title on `push` +commit title on `push`. ### Matching PipelineRun on body payload @@ -367,7 +366,7 @@ The payload body as passed by the Git provider is available in the CEL variable as `body` and you can use this expression to do any filtering on anything the Git provider is sending over: -For example this expression when run on GitHub: +For example, this expression when run on GitHub: ```yaml pipelinesascode.tekton.dev/on-cel-expression: | @@ -377,8 +376,8 @@ pipelinesascode.tekton.dev/on-cel-expression: | ``` will only match if the pull request is targeting the `main` branch, the author -of the pull request is called `superuser` and the action is `synchronize` (ie: -an update occurred on a pull request) +of the pull request is called `superuser` and the action is `synchronize` (i.e.: +an update occurred on a pull request). {{< hint info >}} When matching the body payload in a Pull Request, the GitOps comments such as @@ -390,7 +389,7 @@ payload. Consequently, when a pull request event occurs, like opening or updating a pull request, the CEL body payload may not align with the defined specifications. -To be able to retest your Pull Request when using a CEL on bod payload, +To be able to retest your Pull Request when using a CEL on body payload, you can make a dummy update to the Pull Request by sending a new SHA with this git command: @@ -412,18 +411,18 @@ with the CEL variable `headers`. The headers are available as a list and are always in lower case. -For example this is how to make sure the event is a pull_request on [GitHub](https://docs.github.com/en/webhooks/webhook-events-and-payloads#delivery-headers): +For example, this is how to make sure the event is a pull_request on [GitHub](https://docs.github.com/en/webhooks/webhook-events-and-payloads#delivery-headers): ```yaml pipelinesascode.tekton.dev/on-cel-expression: | headers['x-github-event'] == "pull_request" ``` -## Matching a PipelineRun to a branch with comma +## Matching a PipelineRun to a branch with a comma If you want to match multiple branches but one branch has a comma in there you -will not be able to match it. In that case you can use the html escape entity -`,` as comma in the name of the branch, for example if you want to match +will not be able to match it. In that case, you can use the HTML escape entity +`,` as a comma in the name of the branch, for example, if you want to match main and the branch called `release,nightly` you can do this: ```yaml diff --git a/docs/content/docs/guide/repositorycrd.md b/docs/content/docs/guide/repositorycrd.md index b636dcc6a..7c833d416 100644 --- a/docs/content/docs/guide/repositorycrd.md +++ b/docs/content/docs/guide/repositorycrd.md @@ -11,14 +11,14 @@ The Repository CR serves the following purposes: - Referencing an API secret, username, or API URL if necessary for Git provider platforms that require it (e.g., when using webhooks instead of the GitHub application). -- Providing the last `PipelineRun`statuses for the repository (5 by default). -- Let you declare [custom parameters]({{< relref "/docs/guide/customparams" >}}) - within the `PipelineRun`that can be expanded based on certain filters. +- Providing the last `PipelineRun` statuses for the repository (5 by default). +- Letting you declare [custom parameters]({{< relref "/docs/guide/customparams" >}}) + within the `PipelineRun` that can be expanded based on certain filters. The process involves creating a Repository CR inside the target namespace my-pipeline-ci, using the tkn pac CLI or another method. -For example, this will create a Repo CR for the github repository +For example, this will create a Repo CR for the GitHub repository ```yaml @@ -32,13 +32,13 @@ spec: EOF ``` -With this configuration when an event from the `linda/project` repository +With this configuration, when an event from the `linda/project` repository occurs, Pipelines-as-Code will know it needs to be handled and begin checking out the contents of linda/project to match with the PipelineRun in the .tekton/ directory. If the `PipelineRun` matches via its annotations the event, for example on a -specific branch and event like a `push` or `pull_request`. It will start the +specific branch and event like a `push` or `pull_request`, it will start the `PipelineRun` where the `Repository` CR has been created. You can only start the `PipelineRun` in the namespace where the Repository CR is located. @@ -49,9 +49,9 @@ to explicitly target a specific namespace. However, a Repository CRD must still be created in that namespace for it to be matched. This annotation helps prevent bad actors on a cluster from hijacking -PipelineRun execution to a namespace they don't have access to. It let the user +PipelineRun execution to a namespace they don't have access to. It lets the user specify the ownership of a repo matching the access of a specific namespace on -a cluster +a cluster. To use this feature, add the following annotation to the pipeline: @@ -74,14 +74,14 @@ unless you use the `target-namespace` annotation. ### PipelineRun definition provenance -By default on a `Push` or a `Pull Request`, Pipelines-as-Code will fetch the -PipelineRun definition from the branch of where the event has been triggered. +By default, on a `Push` or a `Pull Request`, Pipelines-as-Code will fetch the +PipelineRun definition from the branch where the event has been triggered. This behavior can be changed by setting the setting `pipelinerun_provenance`. -The setting currently accept two values: +The setting currently accepts two values: - `source`: The default behavior, the PipelineRun definition will be fetched - from the branch of where the event has been triggered. + from the branch where the event has been triggered. - `default_branch`: The PipelineRun definition will be fetched from the default branch of the repository as configured on the git platform. For example `main`, `master`, or `trunk`. @@ -105,10 +105,10 @@ spec: ``` {{< hint info >}} -Letting the user specify the provenance of the PipelineRun definition to default +Letting the user specify the provenance of the PipelineRun definition to the default branch is another layer of security. It ensures that only the one who has the -right to merge commit to the default branch can change the PipelineRun and have -access to the infrastrucutre. +right to merge commits to the default branch can change the PipelineRun and have +access to the infrastructure. {{< /hint >}} ## Concurrency @@ -120,8 +120,7 @@ spec: concurrency_limit: ``` -If there is multiple PipelineRuns matching the event, the PipelineRuns -that match the event will always be started in alphabetical order. +When multiple PipelineRuns match the event, they will be started in alphabetical order. Example: @@ -135,17 +134,17 @@ while the rest will be queued. By default, the GitHub token that Pipelines-as-Code generates is scoped only to the repository where the payload comes from. However, in some cases, the developer team might want the token to allow control over additional repositories. -For example, there might be a CI repository where the `.tekton/pr.yaml` file and source payload might be located, however the build process defined in `pr.yaml` might fetch tasks from a separate private CD repository. +For example, there might be a CI repository where the `.tekton/pr.yaml` file and source payload might be located, however, the build process defined in `pr.yaml` might fetch tasks from a separate private CD repository. You can extend the scope of the GitHub token in two ways: - _Global configuration_: extend the GitHub token to a list of repositories in different namespaces and admin have access to set this configuration. - _Repository level configuration_: extend the GitHub token to a list of repositories that exist in the same namespace as the original repository -and both admin, non-admin have access to set this configuration. +and both admin and non-admin have access to set this configuration. {{< hint info >}} -when using a GitHub webhook, the scoping of the token is what you set when creating your [fine grained personal access token](https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/#creating-personal-access-tokens). +When using a GitHub webhook, the scoping of the token is what you set when creating your [fine-grained personal access token](https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/#creating-personal-access-tokens). {{}} Prerequisite @@ -155,7 +154,7 @@ This setting enables the scoping of the GitHub token to private and public repos ### Scoping the GitHub token using Global configuration -You can use the global configuration to use as a list of repositories used from any Repository CR in any namespaces. +You can use the global configuration to use as a list of repositories used from any Repository CR in any namespace. To set the global configuration, in the `pipelines-as-code` configmap, set the `secret-github-app-scope-extra-repos` key, as in the following example: @@ -195,7 +194,7 @@ The scope of the generated GitHub token is extended to the `owner/project` and ` **Note:** -If any of the repositories does not exist in the namespace, the scoping of the GitHub token fails with an error message as in the following example: +If any of the repositories do not exist in the namespace, the scoping of the GitHub token fails with an error message as in the following example: ```console failed to scope GitHub token as repo owner1/project1 does not exist in namespace test-repo @@ -282,5 +281,5 @@ and the scoping fails for the repository level configuration because the reposit In this example, if the `owner5/project5` repository is not under the `test-repo` namespace, scoping of the GitHub token fails with the following error message: ```yaml - failed to scope github token as repo owner5/project5 does not exist in namespace test-repo + failed to scope GitHub token as repo owner5/project5 does not exist in namespace test-repo ``` diff --git a/docs/content/docs/guide/running.md b/docs/content/docs/guide/running.md index 4bb0fbfb6..9ab099187 100644 --- a/docs/content/docs/guide/running.md +++ b/docs/content/docs/guide/running.md @@ -12,9 +12,9 @@ that are annotated with the appropriate event type. {{< hint info >}} The PipelineRuns definitions are fetched from the `.tekton` directory at the -root of you repository from where the event come from, this is unless you have +root of your repository from where the event comes from, this is unless you have configured the [provenance from the default -branch](../repositorycrd/#pipelinerun-definition-provenance) on you Repository +branch](../repositorycrd/#pipelinerun-definition-provenance) on your Repository CR. {{< /hint >}} @@ -38,9 +38,8 @@ run a PipelineRun on CI: - The author of the pull request has permissions to push to branches inside the repository. -- The author who initiated the pull request is identified in an `OWNERS` files - found in the main directory of the branch that is set as the default branch - on GitHub or your other service provider. +- The author of the pull request is listed in the `OWNERS` file located in the main + directory of the default branch on GitHub or your other service provider. The OWNERS file adheres to a specific format, similar to the Prow OWNERS file format (available at ). We diff --git a/docs/content/docs/install/getting-started.md b/docs/content/docs/install/getting-started.md index e2192bc52..4e697ec6b 100644 --- a/docs/content/docs/install/getting-started.md +++ b/docs/content/docs/install/getting-started.md @@ -9,7 +9,7 @@ This guide will walk you through the process of getting started with Pipelines-a This will start with the installation of Pipelines-as-Code on your cluster, then the creation of a GitHub Application, the creation of a Repository CR to specify -which repository you want to use with Pipelines-as-Code, olnd finally we are +which repository you want to use with Pipelines-as-Code, and finally, we are going to create a simple Pull Request to test that configuration and see how the Pipelines-as-Code flow looks like. @@ -28,8 +28,7 @@ by default. You can also install it manually by applying the YAML files to your cluster or use `tkn pac bootstrap` to do it for you. -The `tkn pac bootstrap` command lets you getting started quickly to try out -Pipelines-as-Code. +The `tkn pac bootstrap` command helps you start using Pipelines-as-Code quickly. If you are running Pipelines-as-Code in production, you should consider installing using a GitOps tool like [OpenShift @@ -37,7 +36,7 @@ GitOps](https://www.openshift.com/learn/topics/gitops/) or [ArgoCD](https://argoproj.github.io/argo-cd/) following the manual installation instructions. -This guide use `tkn pac bootstrap` to get you started. +This guide uses `tkn pac bootstrap` to get you started. {{< hint info >}} Note: this assumes using the public GitHub instance, if you are using GitHub @@ -180,7 +179,7 @@ to provide some helpful defaults for the next commands we will execute. {{< hint info >}} A Repository CR is how you configure Pipelines-as-Code. A CR or Custom -Resourceis a Kubernetes object that is not part of the core Kubernetes API. It's +Resource is a Kubernetes object that is not part of the core Kubernetes API. It's a way to extend Kubernetes with new objects. In this case, we are using a CR to specify which Repository URL (among other [settings]({{< relref "/docs/guide/repositorycrd.md" >}})) we want to use with Pipelines-as-Code and @@ -193,9 +192,7 @@ You are now ready to create a Repository CR with the command: tkn pac create repository ``` -The command try to be smart and helpful, and as soon you are launching it will have -detected the git information of the current repository and ask you if you -want to use those values. +The command tries to be smart and helpful. It detects the git information of the current repository and allows you to keep or change the values. ```console ? Enter the Git repository url (default: https://github.com/chmouel/pac-demo): @@ -228,7 +225,7 @@ customized tailored for the Go programming language (ie: it will add the [golangci-lint](https://hub.tekton.dev/tekton/task/golangci-lint) linter as a task to your PipelineRun). -Feel free to open the file `.tekton/pipelinerun.yaml` and inspect what is +Feel free to open the file `.tekton/pipelinerun.yaml` and inspect what it does. The file has plenty of comments to help you understand how it works. ## Creating a Pull Request @@ -256,7 +253,7 @@ We assume you have already set-up your system to be able to push to GitHub. If t {{< /hint >}} When the branch is pushed you can start creating a new Pull Request by going to -the URL (make sure yourusername is replace with your username) +the URL (make sure yourusername is replaced with your username) As soon as you create the Pull Request you will see that Pipelines-as-Code has @@ -317,7 +314,7 @@ triggered again and this time has succeeded: ## Conclusion -Congratulations! You have now successfully setup Pipelines-as-Code for running +Congratulations! You have now successfully set up Pipelines-as-Code for running Continuous Integration on your repository. Now, you can freely proceed to [customize]({{< relref "/docs/guide/authoringprs.md" >}}) your `.tekton/pipelinerun.yaml` file as per your preferences and include additional tasks as needed.