# PAC Trigger

LLMS index: [llms.txt](https://hummingbird-project.io/llms.txt) | Full content: [llms-full.txt](https://hummingbird-project.io/llms-full.txt)

---

A CLI tool to manually trigger Konflux PAC (Pipelines-as-Code) pipelines for a
specific component and branch. Useful for debugging pipeline issues or
re-running builds without pushing a new commit.

## Usage

```bash
# Trigger pipeline for a component (uses branch HEAD)
pac-trigger --gitlab-project-url https://gitlab.com/org/group/project \
            --component myimage--default--main \
            --cluster-url https://konflux-ui.apps.cluster.example.com

# Trigger with specific commit
pac-trigger --gitlab-project-url https://gitlab.com/org/group/project \
            --component myimage--default--main \
            --commit abc123def456 \
            --cluster-url https://konflux-ui.apps.cluster.example.com

# Dry run (preview without creating)
pac-trigger --gitlab-project-url https://gitlab.com/org/group/project \
            --component myimage--default--main \
            --cluster-url https://konflux-ui.apps.cluster.example.com \
            --dry-run
```

### Options

| Option                  | Description                                    | Default |
|-------------------------|------------------------------------------------|---------|
| `--gitlab-project-url`  | GitLab project URL (required)                  | -       |
| `--component`           | Component name (required)                      | -       |
| `--branch`              | Branch name                                    | `main`  |
| `--commit`              | Specific commit SHA                            | HEAD    |
| `--cluster-url`         | Konflux cluster URL (required)                 | -       |
| `--dry-run`             | Preview PipelineRun without creating           | false   |
| `-v`, `--verbose`       | Enable debug logging                           | false   |

## Installation

```bash
cd pac-trigger
pip install -e .
```

## Prerequisites

- **Kubeconfig**: Context with access to the target Konflux cluster/namespace
- **Repository resource**: PAC Repository must exist for the GitLab project
- **Push template**: Component must have a push template in `.tekton/*.yaml`

## How It Works

1. **Fetch commit**: Gets HEAD commit SHA from GitLab (or uses provided commit)
2. **Fetch template**: Downloads `.tekton/*.yaml` files via GitLab API, finds
   push template matching the component
3. **Get namespace**: Extracts namespace from template metadata
4. **Find credentials**: Looks up PAC Repository resource to find git secret
5. **Create git-auth secret**: Creates ephemeral `pac-trigger-gitauth-*` secret
   with git credentials
6. **Create PipelineRun**: Substitutes template variables and creates the
   PipelineRun
7. **Link secret**: Sets ownerReference on secret for garbage collection
8. **Print URL**: Outputs Konflux UI URL for the PipelineRun

### Template Variables

The following PAC template variables are supported:

| Variable              | Substituted with    |
|-----------------------|---------------------|
| `{{revision}}`        | Commit SHA          |
| `{{target_branch}}`   | Branch name         |
| `{{repo_url}}`        | GitLab project URL  |
| `{{git_auth_secret}}` | Created secret name |

Unsupported template variables will cause an error.

### Labels Added

| Label                    | Value  | Purpose                     |
|--------------------------|--------|-----------------------------|
| `pac-trigger/manual`     | `true` | Identifies manual triggers  |

## Features

- **Template-based**: Fetches PipelineRun templates from `.tekton/*.yaml` files
  via anonymous GitLab API
- **Push-only**: Only triggers push templates (filters by CEL expression)
- **Automatic credentials**: Creates ephemeral git-auth secrets from existing
  PAC Repository secrets
- **Garbage collection**: Secrets are linked to PipelineRun via ownerReference
- **Kubeconfig-based**: Uses local kubeconfig for cluster authentication

## Development

See the main [README][readme] for development workflows.

```bash
make pac-trigger/setup  # Install dependencies
make check              # Lint code (ruff)
make fmt                # Format code
make test               # Run unit tests
make coverage           # Run tests with coverage
```

## Comparison with PAC-triggered Runs

Manually triggered PipelineRuns differ from PAC-triggered ones:

**Present in both:**

- `appstudio.openshift.io/application`
- `appstudio.openshift.io/component`
- `pipelines.appstudio.openshift.io/type: build`
- `build.appstudio.redhat.com/commit_sha`
- `build.appstudio.redhat.com/target_branch`

**Unique to pac-trigger:**

- `pac-trigger/manual: true` label

**Missing (PAC internal metadata):**

- `pipelinesascode.tekton.dev/event-type`
- `pipelinesascode.tekton.dev/sha`
- GitLab status reporting annotations

These differences don't affect pipeline execution—they're used for PAC's
internal tracking and GitLab commit status updates.

## Limitations

- Only push templates supported (not pull-request)
- Only GitLab repositories supported
- Requires existing PAC Repository resource
- No GitLab commit status reporting

## License

This project is licensed under the GNU General Public License v3.0 or later -
see the [LICENSE][license] file for details.

[readme]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/README.md
[license]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/LICENSE