Files
platform-state/docs/tekton-ci-cd.md
T

7.3 KiB

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:

kubectl kustomize clusters/main
kubectl kustomize platform/tekton/config

Render and validate CI state:

kubectl kustomize ci/lolympus-tournament-support
kubectl apply --dry-run=server -k ci/lolympus-tournament-support

Application quality gates:

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:

kubectl get tektonconfig,tektondashboard
kubectl get pipelinerun,taskrun -n tekton-ci
kubectl logs -n tekton-ci -l tekton.dev/pipelineRun=<run-name> --all-containers

Project Structure

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.

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: lolympus-quality
spec:
  workspaces:
    - name: source
  steps:
    - name: test-api
      image: node:26-bookworm-slim@sha256:<pinned-digest>
      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-<full-commit-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.