diff --git a/.agents/skills b/.agents/skills new file mode 120000 index 0000000000..454b8427cd --- /dev/null +++ b/.agents/skills @@ -0,0 +1 @@ +../.claude/skills \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 9aa96e08a4..0000000000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -Refer to @AGENTS.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/README.md b/README.md index 8cb152858f..9ccbdd1693 100644 --- a/README.md +++ b/README.md @@ -77,8 +77,8 @@ Full documentation is at **** Install the CLI and bootstrap your first repository: ```shell -brew install tektoncd/pipelines-as-code/tkn-pac -tkn pac bootstrap github +brew install --cask openshift-pipelines/pipelines-as-code/tektoncd-pac +tkn pac bootstrap ``` Then follow the [getting started tutorial](https://pipelinesascode.com/docs/getting-started/). diff --git a/config/302-pac-configmap.yaml b/config/302-pac-configmap.yaml index 6174affe3b..c035bf2179 100644 --- a/config/302-pac-configmap.yaml +++ b/config/302-pac-configmap.yaml @@ -43,8 +43,8 @@ data: # i.e: "owner/private-repo1, org/repo2" secret-github-app-scope-extra-repos: "" - # The default hub url to use, by default it is artifacthub. - hub-url: "https://artifacthub.io" + # The default hub API url to use, by default it is Artifact Hub's API. + hub-url: "https://artifacthub.io/api/v1" # The default hub catalog type, by default it is artifacthub. # Other supported values: tektonhub (for custom self-hosted Tekton Hub instances) diff --git a/docs/content/docs/api/configmap.md b/docs/content/docs/api/configmap.md index f0d9aa697a..607f71eba4 100644 --- a/docs/content/docs/api/configmap.md +++ b/docs/content/docs/api/configmap.md @@ -57,11 +57,11 @@ secret-github-app-scope-extra-repos: "owner/private-repo1, org/repo2" ### Hub Configuration -{{< param name="hub-url" type="string" default="" id="param-hub-url" >}} -Specifies the default hub URL that Pipelines-as-Code uses to fetch remote tasks. +{{< param name="hub-url" type="string" default="" id="param-hub-url" >}} +Specifies the default hub API URL that Pipelines-as-Code uses to fetch remote tasks. ```yaml -hub-url: "https://artifacthub.io" +hub-url: "https://artifacthub.io/api/v1" ``` {{< /param >}} @@ -89,7 +89,7 @@ Name of the catalog. {{< /param >}} {{< param name="catalog-{N}-url" type="string" id="param-catalog-n-url" >}} -URL of the catalog API. +URL of the catalog API endpoint. {{< /param >}} {{< param name="catalog-{N}-type" type="string" id="param-catalog-n-type" >}} @@ -163,6 +163,16 @@ custom-console-url-pr-tasklog: "https://url/ns/{{ namespace }}/{{ pr }}/logs/{{ {{< /param >}} +{{< param name="custom-console-url-namespace" type="string" id="param-custom-console-url-namespace" >}} +Defines the template URL for namespace-level views in your custom console. +Supports the `{{ namespace }}` variable. + +```yaml +custom-console-url-namespace: "https://url/ns/{{ namespace }}" +``` + +{{< /param >}} + ### Error Detection and Logging {{< param name="error-log-snippet" type="boolean" default="true" id="param-error-log-snippet" >}} @@ -351,7 +361,7 @@ data: secret-github-app-token-scoped: "true" secret-github-app-scope-extra-repos: "org/shared-repo" - hub-url: "https://artifacthub.io" + hub-url: "https://artifacthub.io/api/v1" hub-catalog-type: "artifacthub" remote-tasks: "true" diff --git a/docs/content/docs/api/settings.md b/docs/content/docs/api/settings.md index 8b64fe306f..61e7847f2b 100644 --- a/docs/content/docs/api/settings.md +++ b/docs/content/docs/api/settings.md @@ -32,6 +32,19 @@ settings: {{< /param >}} +{{< param name="gitops_command_prefix" type="string" id="param-gitops-command-prefix" >}} +Sets a custom prefix for GitOps commands such as `/test`, `/retest`, and `/cancel`. +Use a plain word such as `pac`; Pipelines-as-Code adds the leading slash +automatically. For command behavior and examples, see the +[GitOps commands guide]({{< relref "/docs/guides/gitops-commands/advanced" >}}). + +```yaml +settings: + gitops_command_prefix: "pac" +``` + +{{< /param >}} + {{< param name="policy" type="Policy" >}} Defines authorization policies for the repository. These policies control which users can trigger PipelineRuns under different conditions. @@ -270,6 +283,8 @@ Specifies the LLM model for this role. If omitted, Pipelines-as-Code uses provid {{< param name="roles[].on_cel" type="string" id="param-roles-on-cel" >}} Defines a CEL expression that determines when Pipelines-as-Code triggers this role. +Use the structured LLM CEL context, such as `body.event.*`, +`body.pipelineRun.*`, and `body.repository.*`. {{< /param >}} {{< param name="roles[].output" type="string" id="param-roles-output" >}} @@ -321,7 +336,7 @@ settings: - name: "failure-analysis" prompt: "Analyze the following CI/CD failure and suggest fixes" model: "gpt-4" - on_cel: "event_type == 'pull_request' && status == 'failed'" + on_cel: 'body.event.event_type == "pull_request" && body.pipelineRun.status.conditions[0].status == "False"' context_items: commit_content: true error_content: true @@ -385,7 +400,7 @@ spec: 2. Specific fix recommendations 3. Prevention strategies model: "gpt-4" - on_cel: 'event_type == "pull_request" && status == "failed"' + on_cel: 'body.event.event_type == "pull_request" && body.pipelineRun.status.conditions[0].status == "False"' output: "pr-comment" context_items: commit_content: true @@ -397,7 +412,7 @@ spec: - name: "security-review" prompt: "Review this change for potential security issues" model: "gpt-4" - on_cel: 'event_type == "pull_request" && has_label("security-review")' + on_cel: '"security-review" in body.event.pull_request_labels' context_items: commit_content: true pr_content: true diff --git a/docs/content/docs/cli/_index.md b/docs/content/docs/cli/_index.md index e4d780b22f..1373c9b35f 100644 --- a/docs/content/docs/cli/_index.md +++ b/docs/content/docs/cli/_index.md @@ -10,26 +10,32 @@ This section covers the `tkn pac` command-line tool, which you use to install, c Pipelines-as-Code provides a CLI designed to work as a plug-in to the [Tekton CLI (tkn)](https://github.com/tektoncd/cli). With `tkn pac`, you can: * `bootstrap`: Install and configure Pipelines-as-Code with a GitHub App. +* `cel`: Evaluate CEL expressions locally against webhook payloads. +* `completion`: Generate shell completion scripts. * `create` / `delete`: Create or remove a Repository CR linked to your Git repository. * `generate`: Scaffold a starter PipelineRun in your `.tekton/` directory. * `list`: List Repository CRs and their current PipelineRun status. * `describe`: View details of a Repository CR and its associated runs. * `logs`: Stream the logs of a PipelineRun attached to a Repository CR. * `resolve`: Process a PipelineRun locally as Pipelines-as-Code would on the server. -* `webhook`: Add or update webhook secrets for your Git provider. * `info`: Display installation details and test globbing patterns. +* `version`: Show the installed CLI version. +* `webhook`: Add or update webhook secrets for your Git provider. {{< cards >}} {{< card link="installation" title="Installation" subtitle="Install the tkn-pac plugin" >}} {{< card link="bootstrap" title="bootstrap" subtitle="Install PAC and create a GitHub App" >}} + {{< card link="cel" title="cel" subtitle="Evaluate CEL expressions locally" >}} + {{< card link="completion" title="completion" subtitle="Generate shell completion scripts" >}} {{< card link="create" title="create / delete" subtitle="Create or remove a Repository CR" >}} {{< card link="repository" title="list" subtitle="List Repository CRs and status" >}} {{< card link="describe" title="describe" subtitle="Details of a Repository and its runs" >}} {{< card link="generate" title="generate" subtitle="Scaffold a PipelineRun" >}} {{< card link="logs" title="logs" subtitle="Stream PipelineRun logs" >}} {{< card link="resolve" title="resolve" subtitle="Resolve a PipelineRun locally" >}} - {{< card link="webhook" title="webhook" subtitle="Add or update webhook secrets" >}} {{< card link="info" title="info" subtitle="Installation details and globbing" >}} + {{< card link="version" title="version" subtitle="Show the installed CLI version" >}} + {{< card link="webhook" title="webhook" subtitle="Add or update webhook secrets" >}} {{< /cards >}} ## Screenshot diff --git a/docs/content/docs/cli/bootstrap.md b/docs/content/docs/cli/bootstrap.md index 125256bf25..67d8004aa6 100644 --- a/docs/content/docs/cli/bootstrap.md +++ b/docs/content/docs/cli/bootstrap.md @@ -42,4 +42,10 @@ Do not use gosmee in production environments. It is intended for testing only. ## bootstrap github-app -To create only a GitHub App without running the full bootstrap process, use `tkn pac bootstrap github-app`. This skips the installation step and only creates the GitHub App and the corresponding secret in the `pipelines-as-code` namespace. +Use `tkn pac bootstrap github-app` when you want help creating the GitHub App without running the full interactive bootstrap flow. + +This command does not perform the installation flow from `tkn pac bootstrap`. It creates the GitHub App configuration and the corresponding secret for a fresh Pipelines-as-Code setup. + +{{< callout type="info" >}} +If Pipelines-as-Code is already installed, the command exits unless you pass `--force-install`. +{{< /callout >}} diff --git a/docs/content/docs/cli/completion.md b/docs/content/docs/cli/completion.md index 23498d10aa..cf10fb1d18 100644 --- a/docs/content/docs/cli/completion.md +++ b/docs/content/docs/cli/completion.md @@ -39,6 +39,12 @@ Load completions in the current session: source <(tkn pac completion zsh) ``` +If shell completion is not already enabled in your environment, run this once first: + +```shell +echo "autoload -U compinit; compinit" >> ~/.zshrc +``` + To load completions automatically for every session, run once: ```shell @@ -58,3 +64,11 @@ To load completions automatically for every session, run once: ```shell tkn pac completion fish > ~/.config/fish/completions/tkn-pac.fish ``` + +### PowerShell + +Load completions in the current session: + +```powershell +tkn pac completion powershell | Out-String | Invoke-Expression +``` diff --git a/docs/content/docs/cli/create.md b/docs/content/docs/cli/create.md index c8fe1b9e8c..e112429509 100644 --- a/docs/content/docs/cli/create.md +++ b/docs/content/docs/cli/create.md @@ -9,7 +9,7 @@ Use `tkn pac create` and `tkn pac delete` to manage Repository CRs. These comman ```shell tkn pac create repo -tkn pac delete repo [--cascade] +tkn pac delete repo [--cascade] ``` ## Creating a Repository CR @@ -20,6 +20,6 @@ If you have not configured a Git provider previously, the command prompts you to ## Deleting a Repository CR -`tkn pac delete repo` deletes a Repository CR. +`tkn pac delete repo ` deletes a Repository CR. You can also use the full subcommand name, `tkn pac delete repository `. Specify the `--cascade` flag to also delete the attached secrets (such as webhook or provider secrets) associated with the Repository CR. diff --git a/docs/content/docs/cli/installation.md b/docs/content/docs/cli/installation.md index 0d8717ccb1..fa43dedfad 100644 --- a/docs/content/docs/cli/installation.md +++ b/docs/content/docs/cli/installation.md @@ -27,7 +27,7 @@ On Windows, tkn-pac will look for the Kubernetes config in `%USERPROFILE%\.kube\ {{< /tab >}} {{< tab name="Homebrew" >}} -The `tkn pac` plug-in is available from Homebrew as a "Tap". Install it with: +The `tkn pac` plug-in is available from Homebrew as a cask. Install it with: ```shell brew install --cask openshift-pipelines/pipelines-as-code/tektoncd-pac diff --git a/docs/content/docs/dev/architecture.md b/docs/content/docs/dev/architecture.md index 89d80d7a70..24721d8ce1 100644 --- a/docs/content/docs/dev/architecture.md +++ b/docs/content/docs/dev/architecture.md @@ -408,8 +408,8 @@ data: # Application settings application-name: "Pipelines as Code" - # Tekton Hub URL - hub-url: "https://api.hub.tekton.dev/v1" + # Artifact Hub API URL + hub-url: "https://artifacthub.io/api/v1" # Remote tasks support remote-tasks: "true" diff --git a/docs/content/docs/guides/llm-analysis/_index.md b/docs/content/docs/guides/llm-analysis/_index.md index 8819c45534..57fd41a9bb 100644 --- a/docs/content/docs/guides/llm-analysis/_index.md +++ b/docs/content/docs/guides/llm-analysis/_index.md @@ -93,7 +93,7 @@ Each role defines a specific analysis scenario. You can configure multiple roles | `name` | string | Yes | Unique identifier for this role | | `prompt` | string | Yes | Prompt template for the LLM | | `model` | string | No | Model name (consult provider documentation for available models). Uses provider default if not specified. | -| `on_cel` | string | No | CEL expression for conditional triggering. If not specified, the role will always run. | +| `on_cel` | string | No | CEL expression for conditional triggering. If not specified, the role runs only for failed PipelineRuns. | | `output` | string | Yes | Output destination (currently only `pr-comment` is supported) | | `context_items` | object | No | Configuration for context inclusion | @@ -129,4 +129,3 @@ When you set `commit_content: true`, Pipelines-as-Code includes the following fi - Pipelines-as-Code **intentionally excludes email addresses** from the commit context to protect personally identifiable information (PII) when sending data to external LLM providers. - Fields appear only if your Git provider makes them available. Some providers supply limited information (for example, Bitbucket Cloud provides only the author name). - Author and committer may be the same person or different (for example, when using `git commit --amend` or rebasing). -asing). diff --git a/docs/content/docs/guides/repository-crd/comment-settings.md b/docs/content/docs/guides/repository-crd/comment-settings.md index 418b715171..7ea4d22ee0 100644 --- a/docs/content/docs/guides/repository-crd/comment-settings.md +++ b/docs/content/docs/guides/repository-crd/comment-settings.md @@ -7,10 +7,10 @@ This page explains how to control the volume and behavior of Pull/Merge Request For GitHub (Webhook), GitLab, and Gitea/Forgejo integrations, you can control which Pull/Merge Request comments Pipelines-as-Code posts by using -the `spec..comment_strategy` setting. This is useful for reducing notification +the `spec.settings..comment_strategy` setting. This is useful for reducing notification volume in repositories that use long-lasting Pull/Merge Requests with many PipelineRuns. -The `spec..comment_strategy` field accepts `""` +The `spec.settings..comment_strategy` field accepts `""` (default), `"update"`, and `"disable_all"`. Setting `comment_strategy` to `update` creates a single comment for diff --git a/docs/content/docs/guides/repository-crd/github-token-scoping.md b/docs/content/docs/guides/repository-crd/github-token-scoping.md index 18951befa0..3341692d70 100644 --- a/docs/content/docs/guides/repository-crd/github-token-scoping.md +++ b/docs/content/docs/guides/repository-crd/github-token-scoping.md @@ -23,14 +23,21 @@ When using a GitHub webhook, the scoping of the token is what you set when creat ## Prerequisites - You must have Pipelines-as-Code installed with the **GitHub App** method. Token scoping does not apply to webhook-based installations because the token scope is determined by your personal access token. -- In the `pipelines-as-code` ConfigMap, set the `secret-github-app-token-scoped` key to `false`. -This setting enables Pipelines-as-Code to scope the GitHub token to private and public repositories listed in the global and repository level configuration. + +| Scoping method | `secret-github-app-token-scoped` setting | +| --- | --- | +| **Global** (`secret-github-app-scope-extra-repos`) | Can stay `true` (default) | +| **Repository-level** (`settings.github_app_token_scope_repos`) | Must be `false` | +| **Both combined** | Can stay `true` | ## Scoping the GitHub token using Global configuration Use the global configuration to define a list of repositories accessible from any Repository CR in any namespace. You can specify repositories using exact names or glob patterns (for example, `myorg/*` to match all repositories under an organization where the app is installed). +Unlike repository-level scoping, this global configuration does not require you to disable +`secret-github-app-token-scoped`. + To set the global configuration, add the `secret-github-app-scope-extra-repos` key to the `pipelines-as-code` ConfigMap as shown in the following example: ```yaml @@ -49,6 +56,10 @@ You can also use the Repository CR to scope the generated GitHub token to a list The repositories can be public or private, but must reside in the same namespace as the Repository CR. You can specify repositories using exact names or glob patterns (for example, `myorg/*` to match all repositories under an organization that has the GitHub App installed). +When you use only `settings.github_app_token_scope_repos`, set +`secret-github-app-token-scoped` to `false`. Otherwise Pipelines-as-Code rejects the +repository-level scope extension request. + Set the `github_app_token_scope_repos` field in the Repository CR spec, as shown in the following example: ```yaml diff --git a/docs/content/docs/installation/openshift.md b/docs/content/docs/installation/openshift.md index 8864ed40b8..b89583c0c1 100644 --- a/docs/content/docs/installation/openshift.md +++ b/docs/content/docs/installation/openshift.md @@ -57,7 +57,7 @@ spec: enable-cancel-in-progress-on-pull-requests: 'false' enable-cancel-in-progress-on-push: 'false' skip-push-event-for-pr-commits: 'true' - hub-url: 'https://artifacthub.io' + hub-url: 'https://artifacthub.io/api/v1' hub-catalog-type: 'artifacthub' error-detection-max-number-of-lines: '50' error-detection-simple-regexp: >- diff --git a/docs/content/docs/installation/overview.md b/docs/content/docs/installation/overview.md index d432318b61..6869b49ea1 100644 --- a/docs/content/docs/installation/overview.md +++ b/docs/content/docs/installation/overview.md @@ -26,3 +26,4 @@ After installing Pipelines-as-Code, configure your Git provider to send webhook * [GitLab]({{< relref "/docs/providers/gitlab" >}}) * [Bitbucket Data Center]({{< relref "/docs/providers/bitbucket-datacenter" >}}) * [Bitbucket Cloud]({{< relref "/docs/providers/bitbucket-cloud" >}}) +* [Forgejo]({{< relref "/docs/providers/forgejo" >}}) diff --git a/docs/content/docs/installation/requirements.md b/docs/content/docs/installation/requirements.md index 39d7aea964..c0b41ff5a9 100644 --- a/docs/content/docs/installation/requirements.md +++ b/docs/content/docs/installation/requirements.md @@ -55,21 +55,25 @@ You need the following tools to interact with your cluster and manage Pipelines- ### Required Tools -1 +1. `kubectl` -kubectl +The Kubernetes command-line tool for cluster access. -The Kubernetes command-line tool for cluster access.**Installation**: [kubectl installation guide](https://kubernetes.io/docs/tasks/tools/)**Verify**: +**Installation**: [kubectl installation guide](https://kubernetes.io/docs/tasks/tools/) + +**Verify**: ```bash kubectl version --client ``` -2 +1. `oc` (OpenShift only) -oc (OpenShift only) +The OpenShift command-line tool. -The OpenShift command-line tool.**Installation**: [OpenShift CLI tools](https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html)**Verify**: +**Installation**: [OpenShift CLI tools](https://docs.openshift.com/container-platform/latest/cli_reference/openshift_cli/getting-started-cli.html) + +**Verify**: ```bash oc version @@ -79,11 +83,13 @@ oc version These tools enhance the Pipelines-as-Code experience: -1 +1. `tkn` + +The Tekton CLI for managing Tekton resources. -tkn +**Installation**: [Tekton CLI installation](https://tekton.dev/docs/cli/) -The Tekton CLI for managing Tekton resources.**Installation**: [Tekton CLI installation](https://tekton.dev/docs/cli/)**Install via Homebrew**: +**Install via Homebrew**: ```bash brew install tektoncd-cli @@ -95,14 +101,14 @@ brew install tektoncd-cli tkn version ``` -2 +1. `tkn-pac` -tkn-pac +The Pipelines-as-Code CLI plugin for `tkn`. -The Pipelines-as-Code CLI plugin for tkn.**Install via Homebrew**: +**Install via Homebrew**: ```bash -brew install openshift-pipelines/pipelines-as-code/tkn-pac +brew install --cask openshift-pipelines/pipelines-as-code/tektoncd-pac ``` **Install via Direct Download** (Linux): diff --git a/docs/content/docs/providers/forgejo.md b/docs/content/docs/providers/forgejo.md index c80ffef974..e1724bbe58 100644 --- a/docs/content/docs/providers/forgejo.md +++ b/docs/content/docs/providers/forgejo.md @@ -35,7 +35,9 @@ These scopes are necessary for basic Pipelines-as-Code functionality: - **Organization** (Read) - Only required if using [team-based policies]({{< relref "/docs/advanced/policy-authorization" >}}) to restrict pipeline triggers based on Forgejo organization team membership {{< callout type="info" >}} -For most users, only the **Required Scopes** are needed. Skip Organization (Read) unless you plan to use `policy.team_ids` in your Repository CR configuration. +For most users, only the **Required Scopes** are needed. Skip Organization (Read) +unless you plan to use `settings.policy.ok_to_test` or +`settings.policy.pull_request` in your Repository CR configuration. {{< /callout >}} Store the generated token in a safe place, or you will have to recreate it. @@ -91,13 +93,10 @@ kubectl -n target-namespace create secret generic forgejo-webhook-config \ --from-literal webhook.secret="SECRET_AS_SET_IN_WEBHOOK_CONFIGURATION" ``` -If you configured an empty webhook secret, use an empty string: - -```shell -kubectl -n target-namespace create secret generic forgejo-webhook-config \ - --from-literal provider.token="TOKEN_AS_GENERATED_PREVIOUSLY" \ - --from-literal webhook.secret="" -``` +{{< callout type="warning" >}} +Forgejo and Gitea webhook validation requires a non-empty shared secret. +Do not set `webhook.secret` to an empty string. +{{< /callout >}} ### Create the Repository CR diff --git a/pkg/cmd/tknpac/completion/cmd.go b/pkg/cmd/tknpac/completion/cmd.go index 49e0b73e33..c9f4869209 100644 --- a/pkg/cmd/tknpac/completion/cmd.go +++ b/pkg/cmd/tknpac/completion/cmd.go @@ -39,7 +39,7 @@ Linux: $ tkn-pac completion bash > /etc/bash_completion.d/tkn-pac MacOS: - $ tkn-pac completion bash > /usr/local/etc/bash_completion.d/tkn-pac + $ tkn-pac completion bash > $(brew --prefix)/etc/bash_completion.d/tkn-pac Zsh: