Files
platform-state/docs/tekton-ci-cd.md
T
dahyeon 79268872f6 docs: define Tekton staging delivery contract
Document repository ownership, credential boundaries, quality gates, immutable release identifiers, and the GitOps verification plan before adding CI resources.
2026-07-18 07:07:52 +00:00

6.6 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
        corepack pnpm --filter api test -- --runInBand

Do not use mutable image tags such as latest, inline credentials, or direct kubectl set image deployment mutations.

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.

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 in read-only mode.
  • 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.