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

240 lines
8.4 KiB
Markdown

# 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=<run-name> --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.
## Registering Additional Service CI
CI directories in `service-state` are registered explicitly; the service
ApplicationSets discover only `apps/*/overlays/*`.
For URL shortener, `argocd/applications/url-shortener-ci.yaml` reconciles
`service-state/ci/url-shortener` into `tekton-ci` using the `ci` project.
The platform root Application discovers this registration recursively.
Cluster-scoped EventListener RBAC belongs in
`platform/tekton/config/eventlistener-rbac.yaml`. Each listener receives a
dedicated ClusterRole and ClusterRoleBinding allowing only `get`, `list`, and
`watch` on `clusterinterceptors` and `clustertriggerbindings`.
Keep ServiceAccounts, Roles, and RoleBindings in `service-state`; remove the
URL shortener ClusterRoleBinding from its `foundation.yaml` when adopting this
registration. The `ci` project intentionally does not allow cluster resources.
Before the first URL shortener run, configure its Infisical secrets and Gitea
push webhook at `https://tekton-hook.dahyeon.us/url-shortener` as defined in
`service-state/ci/url-shortener`.
## 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:<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.