Document repository ownership, credential boundaries, quality gates, immutable release identifiers, and the GitOps verification plan before adding CI resources.
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:
- validate the API and web applications;
- build and push an immutable API image to Harbor;
- deploy the web application to the Cloudflare Pages
stagingbranch; and - 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 accessGITEA_TOKEN: token for that bot accountHARBOR_DOCKER_CONFIG_JSON: Docker config JSON for a project-scoped robotCLOUDFLARE_API_TOKEN: token scoped to Pages deploymentsCLOUDFLARE_ACCOUNT_ID: Cloudflare account identifierGITEA_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-supportandrefs/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-pathvolume claim per PipelineRun
Testing Strategy
- Static:
git diff --checkand 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
TektonConfigand all required controllers are Ready.https://tekton.dahyeon.usreturns 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
- Add
tekton-cinamespace and bounded namespace resources. - Add Infisical-backed, purpose-specific CI Secrets.
- Add clone, quality, BuildKit, latest-revision, Cloudflare, and GitOps Tasks.
- Compose the staging Pipeline and signed Gitea Trigger.
- Add a TLS Ingress at
tekton-hook.dahyeon.us. - Add the restricted Argo CD project and Application.
- Validate a signed webhook end to end after the Infisical values exist.