From 79268872f6ce8a3b00bbfd7073e9a76bdc035625 Mon Sep 17 00:00:00 2001 From: Park Dahyeon Date: Sat, 18 Jul 2026 07:07:52 +0000 Subject: [PATCH] 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. --- docs/tekton-ci-cd.md | 203 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 docs/tekton-ci-cd.md diff --git a/docs/tekton-ci-cd.md b/docs/tekton-ci-cd.md new file mode 100644 index 0000000..a18955c --- /dev/null +++ b/docs/tekton-ci-cd.md @@ -0,0 +1,203 @@ +# 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 + 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-` +- 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. +