local-dev-setup

Files (3)

• SKILL.md
• apply-konflux-cr.sh · scripts/
• wait-for-konflux.sh · scripts/

SKILL.md (first lines)

# Local Development Setup

Deploy Konflux on a local Kind cluster. Two modes are available:

- **Development** (`OPERATOR_INSTALL_METHOD=none`) — operator runs on the host for fast rebuild-restart cycles. **This is the default mode for this skill.**
- **Preview** (`checkout`, `release`, or `build`) — operator runs in-cluster; `deploy-local.sh` handles everything end-to-end.

If the user doesn't specify, use **development** mode. Ask only if their intent is ambiguous.

Full documentation: `operator/docs/content/docs/installation/install-local.md`

## Prerequisites

- `kind`, `kubectl`, `podman` (or `docker`)
- `helm` (only for sigstore integration)
- A configured `scripts/deploy-local.env` file (see "Env File" section)

## Env File

The env file at `scripts/deploy-local.env` must exist before running. If it doesn't, copy the template:

```bash
cp scripts/deploy-local.env.template scripts/deploy-local.env
```

Required secrets (must already be populated by the user — never generate or guess these):

| Variable | Description |
|----------|-------------|
| `GITHUB_APP_ID` | Numeric GitHub App ID |
| `GITHUB_PRIVATE_KEY` or `GITHUB_PRIVATE_KEY_PATH` | PEM key content or path to .pem file |
| `WEBHOOK_SECRET` | GitHub webhook secret |

GitHub App setup guide: `operator/docs/content/docs/guides/github-secrets.md`

### OPERATOR_INSTALL_METHOD values

| Value | Mode | Description |
|-------|------|-------------|
| `none` | Development | Operator runs on host via `make run` |
| `checkout` | Preview | Checkout manifests + Quay image tagged with git SHA |
| `release` | Preview | Released install.yaml + released sample CR |
| `build` | Preview | Build operator image from source |

Set the appropriate value in `deploy-local.env` before running. If the file already has a different value, change it using StrReplace.

## (Optional) Delete and Recreate the Kind Cluster

If the user asks to recreate the cluster, or if the cluster is in a broken state, delete it first:

```bash
kind delete cluster --name konflux
```

The containerd image cache (`~/.cache/konflux-ci/containerd-cache`) persists across cluster deletions when `ENABLE_IMAGE_CACHE=1`, making recreation much faster. **Do not clear the cache** unless the user explicitly asks or there is a specific issue (e.g. corrupted images, Kubernetes version change):

```bash
rm -rf ~/.cache/konflux-ci/containerd-cache
```

---

## Development Mode (operator outside cluster)

Use this when the user is developing the operator and needs fast iteration.

### Checklist

Track progress with TodoWrite:

```
- [ ] Ensure scripts/deploy-local.env exists and has OPERATOR_INSTALL_METHOD=none
- [ ] (Optional) Delete existing Kind cluster
- [ ] Run deploy-local.sh to create cluster and deploy dependencies
- [ ] Install CRDs: cd operator && make install
- [ ] Run operator locally: cd operator && make run
- [ ] Apply the Konflux CR
- [ ] Wait for Konflux to become ready
- [ ] (Optional) Install integrations
```

### Step 1: Set OPERATOR_INSTALL_METHOD=none

Verify `scripts/deploy-local.env` has:

```
OPERATOR_INSTALL_METHOD=none
```

### Step 2: Deploy Cluster and Dependencies

```bash
./scripts/deploy-local.sh
```

This creates the Kind cluster and installs dependencies (Tekton, cert-manager, etc.) but skips operator installation. Takes several minutes. Use `block_until_ms: 0` and poll the terminal for "Deployment Complete!" or an error.

### Step 3: Install CRDs and Run the Operator

From the `operator/` directory:

```bash
cd operator && make install
```

Then start the operator — this is a long-running process, background it immediately:

```bash
make run
```

Use `block_until_ms: 0` for `make run` since it runs indefinitely. Poll the terminal to confirm startup (look for "Starting workers" or controller log lines).

### Step 4: Apply the Konflux CR and Wait

In a **separate** shell (the operator terminal is occupied), apply the CR using the shim script. It uses `scripts/resolve-konflux-cr.sh` to pick the right CR (defaults to the base CR; auto-selects `konflux-e2e.yaml` when Quay credentials are set).

**Run these commands from the repository root** (use `working_directory` parameter pointing to the repo root, since the previous step leaves the shell in `operator/`):

From konflux-ci/konflux-ci, Apache-2.0.

More from konflux-ci/konflux-ci