# Spec: Tekton CI/CD for lolympus-tournament-support ## Objective Build a GitOps-native staging delivery path for the lolympus monorepo on the existing k3s cluster. A push to the source repository's `main` branch must: 1. validate the API and web applications; 2. build and push an immutable API image to Harbor; 3. deploy the web application to the Cloudflare Pages `staging` branch; and 4. update only the staging image tag in `service-state`. Argo CD remains the only component that deploys Kubernetes workloads. Production promotion remains a separate PR/manual operation. ## Tech Stack - Kubernetes: k3s v1.35.5+k3s1, amd64, containerd - GitOps: Argo CD with Kustomize - CI: Tekton Operator v0.79.1, Pipelines v1.9.3, Triggers v0.35.0 - Image builder: BuildKit v0.31.1 rootless, pinned by digest - Source and GitOps hosting: Gitea at `git.dahyeon.us` - Image registry: `registry.dahyeon.us/lolympus/lolympus-tournament-support` - Web hosting: Cloudflare Pages project `lolympus` - Secret management: Infisical Secrets Operator ## Commands Render platform state: ```bash kubectl kustomize clusters/main kubectl kustomize platform/tekton/config ``` Render and validate CI state: ```bash kubectl kustomize ci/lolympus-tournament-support kubectl apply --dry-run=server -k ci/lolympus-tournament-support ``` Application quality gates: ```bash corepack pnpm install --frozen-lockfile corepack pnpm --filter api exec eslint "{src,apps,libs,test}/**/*.ts" --max-warnings=0 corepack pnpm --filter web lint corepack pnpm --filter api test -- --runInBand corepack pnpm --filter web test node --test scripts/deploy-cloudflare-pages.test.mjs corepack pnpm --filter api build corepack pnpm --filter web build:staging corepack pnpm audit --prod --audit-level high ``` Runtime verification: ```bash kubectl get tektonconfig,tektondashboard kubectl get pipelinerun,taskrun -n tekton-ci kubectl logs -n tekton-ci -l tekton.dev/pipelineRun= --all-containers ``` ## Project Structure ```text platform-state/ docs/tekton-ci-cd.md clusters/main/namespaces.yaml argocd/projects/ci.yaml argocd/applications/lolympus-tournament-support-ci.yaml service-state/ ci/lolympus-tournament-support/ kustomization.yaml foundation.yaml infisical-secret.yaml tasks.yaml pipeline.yaml trigger.yaml ingress.yaml ``` Tekton controllers stay in `tekton-pipelines`. Application PipelineRuns and their credentials run in the isolated `tekton-ci` namespace. ## Code Style Use stable Tekton APIs, explicit names, immutable image references, bounded resources, and namespace-scoped RBAC. ```yaml apiVersion: tekton.dev/v1 kind: Task metadata: name: lolympus-quality spec: workspaces: - name: source steps: - name: test-api image: node:26-bookworm-slim@sha256: workingDir: $(workspaces.source.path) script: | #!/bin/sh set -eu pnpm --filter api test --runInBand ``` Do not use mutable image tags such as `latest`, inline credentials, or direct `kubectl set image` deployment mutations. The pinned Node 26 image does not include Corepack. The Tasks bootstrap exactly `pnpm@10.4.1` into the shared workspace before running package scripts. ## Secret Contract Infisical project `8520b8c0-3796-4fd6-a03c-6f0508c8c42c`, environment `prod`, path `/platform/tekton/lolympus-tournament-support` must contain: - `GITEA_USERNAME`: bot account with source read and service-state write access - `GITEA_TOKEN`: token for that bot account - `HARBOR_DOCKER_CONFIG_JSON`: Docker config JSON for a project-scoped robot - `CLOUDFLARE_API_TOKEN`: token scoped to Pages deployments - `CLOUDFLARE_ACCOUNT_ID`: Cloudflare account identifier - `GITEA_WEBHOOK_SECRET`: high-entropy webhook signing secret The source test/build Tasks do not receive Gitea, Harbor, or Cloudflare credentials. Credential Secrets are mounted only into the Tasks that require them. ## External Setup - Create the Infisical path and all six keys in the Secret Contract before the first run. - Point public DNS for `tekton-hook.dahyeon.us` to the same public ingress endpoint as `tekton.dahyeon.us`. - In Gitea, add an active push webhook for `https://tekton-hook.dahyeon.us` with JSON content type and use the exact `GITEA_WEBHOOK_SECRET` value as its signing secret. - Protect `https://tekton.dahyeon.us` with an authentication layer such as Cloudflare Access when build metadata and logs must not be public. ## Pipeline Contract - Trigger: signed Gitea push event for exactly `dahyeon/lolympus-tournament-support` and `refs/heads/main` - Source revision: the full 40-character commit SHA from the webhook - Image tag: `sha-` - Cloudflare Pages branch: `staging` - GitOps target: `apps/lolympus-tournament-support/overlays/staging/kustomization.yaml` - Superseded runs must not update `service-state` - A failure in any quality, image, or Cloudflare step must prevent GitOps update - Pipeline timeout: 45 minutes - Workspace: 10 GiB `local-path` volume claim per PipelineRun ## Testing Strategy - Static: `git diff --check` and Kustomize rendering for every state repo - Schema: client dry-run before namespace creation, server dry-run afterwards - Application: run every command listed under Application quality gates - Integration: send a signed test webhook and verify one PipelineRun is created - End-to-end: verify Harbor tag, Cloudflare staging deployment, service-state commit, and Argo CD staging sync all refer to the same source SHA - Rollback: revert the service-state tag commit and manually redeploy the prior Cloudflare source revision if required ## Boundaries Always: - use Argo CD for persistent cluster resources; - use immutable source and image revisions; - validate webhook signatures and repository/branch fields; - keep RBAC namespace-scoped and resource-limited; - keep production promotion manual. Ask first: - enabling automatic production sync; - changing the Harbor repository or Cloudflare project; - granting CI credentials access to additional repositories; - enabling privileged image builds. Never: - store secret values in Git; - pass a repository URL from an untrusted webhook directly to a clone Task; - expose credentials to application test or build steps; - mutate staging Deployments directly with kubectl; - deploy an unverified pull request with production-capable credentials. ## Success Criteria - `TektonConfig` and all required controllers are Ready. - `https://tekton.dahyeon.us` returns HTTP 200 with read-only mode disabled. - A valid main push creates exactly one staging PipelineRun. - Invalid signatures, repositories, branches, and malformed SHAs are rejected. - Quality gates complete before side effects. - The Harbor tag, Cloudflare staging deployment, and service-state staging tag identify the same source commit. - Argo CD automatically deploys staging and leaves production unchanged. - Finished runs and their PVCs are pruned according to the configured policy. ## Implementation Plan 1. Add `tekton-ci` namespace and bounded namespace resources. 2. Add Infisical-backed, purpose-specific CI Secrets. 3. Add clone, quality, BuildKit, latest-revision, Cloudflare, and GitOps Tasks. 4. Compose the staging Pipeline and signed Gitea Trigger. 5. Add a TLS Ingress at `tekton-hook.dahyeon.us`. 6. Add the restricted Argo CD project and Application. 7. Validate a signed webhook end to end after the Infisical values exist.