Blaster repo and branches

info

This page explains how repos, branches and environments connect together for the Blaster game. It is the reference for where to commit what, and how code flows from local dev to k8s dev and k8s prod.

Blaster GitOps series

1. Blaster GitOps summary
2. Blaster repo and branches - you are here
3. Dockerfile & GitLab CI
4. Clerk authentication & user setup
5. Google OAuth for Clerk
6. Blaster prep for automation
7. Dev app k8s manifests
8. Dev flux sources & Kustomizations
9. Dev image automation
10. Dev SOPS & age
11. Dev verification & troubleshooting
12. Dev full runbook
13. Prod overview
14. Prod app k8s manifests and deployment
15. Prod Flux GitOps and image automation
16. Prod Cloudflare, Origin CA and tunnel routing
17. Prod full runbook
18. Post development branches

1. Repos at a glance

You use two GitLab repos:

Repo	Type	Purpose
games/blaster	App repo	Game code, Dockerfile, .gitlab-ci.yml, app k8s manifests.
fluxgitops/flux-config	Infra repo	Flux bootstrap, cluster config and Blaster GitOps configuration.

1.1 App repo: games/blaster

Contains:

• Next.js + Phaser app code under app/, public/ and friends.
• A single Dockerfile at repo root for both dev and prod images.
• .gitlab-ci.yml that:
  • Runs lint and test on all branches.
  • Builds and pushes images for develop and main using Kaniko.
• Kubernetes manifests under k8s/:
  • k8s/dev for the blaster-dev namespace.
  • k8s/prod for the blaster namespace.

1.2 Infra repo: fluxgitops/flux-config

Contains:

• Flux bootstrap config under clusters/my-cluster/flux-system.
• Cluster-wide apps (including Blaster) under clusters/my-cluster/....
• Blaster-specific Flux configuration under clusters/my-cluster/blaster:
  • Namespace manifest.
  • GitRepository and Kustomization for the app repo.
  • ImageRepository, ImagePolicy and ImageUpdateAutomation.
  • Registry Secrets encrypted with SOPS.

The app repo owns the app manifests; the infra repo owns how Flux points at them.

---

2. Branches and environments

Blaster uses a simple branch-per-stage model in the app repo:

Branch	Environment	Namespace	URL	Who pushes
main	Production	blaster	https://blaster.muppit.au	Merge requests only
develop	k8s dev	blaster-dev	https://blaster.reids.net.au	Merge requests only
feature/*	Local feature work	Local only	npm run dev on Mac. http://localhost:3000	Direct by developer

Rules:

• main and develop are protected branches in GitLab.
• All changes to main and develop go through merge requests.
• Feature branches are short-lived and manually deleted after merge.

---

3. Local, dev and prod states

There are three main states for the Blaster game:

1. Local dev (Mac)
   • Code on a feature/* branch.
   • .env.local for secrets and local DB connection.
   • Run with npm run dev.
2. k8s dev
   • develop branch is deployed by Flux to the blaster-dev namespace.
   • Uses manifests from k8s/dev and dev- image tags.
   • Ingress host: blaster.reids.net.au (internal).
3. k8s prod
   • main branch is deployed by Flux to the blaster namespace.
   • Uses manifests from k8s/prod and prod- image tags.
   • Ingress host: blaster.muppit.au via Cloudflare tunnel.

Promotion is branch based:

• Feature branch → develop (dev environment).
• develop → main (prod environment).

---

4. Git history and tag strategy

4.1 Image tag format

GitLab CI builds tags in the app repo:

• On develop:
  • registry.reids.net.au/games/blaster:dev-YYYYMMDD.N
• On main:
  • registry.reids.net.au/games/blaster:prod-YYYYMMDD.N

Where:

• YYYYMMDD is the build date.
• N is the GitLab pipeline IID.

Flux image policies in the infra repo:

• Watch registry.reids.net.au/games/blaster.
• Select the latest dev- tag for k8s dev.
• Select the latest prod- tags for k8s prod.

4.2 Git rules of thumb

• Only tag or release artefacts from main.
• Keep develop reasonably clean and deployable.
• Rebase or squash feature branches if you want a tidy history.

---

5. Typical workflow

5.1 From feature branch to k8s dev

1. Create a feature branch from develop:
   • git checkout develop
   • git pull
   • git checkout -b feature/new-thing
2. Develop locally on your workstation.
3. Push the branch and open a merge request into develop.
4. GitLab CI:
   • Runs lint and tests.
   • Builds a dev-YYYYMMDD.N image when the merge lands on develop.
5. Flux in the cluster:
   • Sees the updated develop branch.
   • Applies k8s/dev manifests.
   • Image automation updates the app Deployment to the latest dev- tag.

You then test Blaster locally at https://blaster.reids.net.au.

5.2 Promotion to k8s prod

Once dev looks good:

1. Open a merge request from develop into main.
2. Review and merge when the pipeline passes.
3. GitLab CI:
   • Builds a prod-YYYYMMDD.N image from main.
4. Flux blaster-prod Kustomization:
   • Syncs k8s/prod manifests.
   • Uses the prod tag defined in the prod Deployment.

Blaster updates on https://blaster.muppit.au.

---

6. Branch protection and permissions

Recommended GitLab settings for the app repo:

• Protected branches:
  • main:
    • Allowed to merge: Maintainers (and any other trusted role).
    • Allowed to push: No one, or Maintainers only.
  • develop:
    • Same pattern as main.
• Merge request rules:
  • Require pipeline to succeed before merge.
  • Optionally require code review approvals.
• Fast-forward behaviour:
  • You can allow merge commits or squash merges.
  • Keep it consistent across the repo.

This keeps main and develop clean and forces changes to go via CI.

---

7. Final state manifests (dev and prod)

In the app repo:

games/blaster/
├── .dockerignore
├── .gitlab-ci.yml
├── .sops.yaml
├── app
├── database
├── db
├── Dockerfile
├── k8s
│   ├── dev
│   │   ├── 10-secret-db.enc.yaml
│   │   ├── 20-db-statefulset.yaml
│   │   ├── 30-secret-app.enc.yaml
│   │   ├── 40-app-config.yaml
│   │   ├── 50-app-deployment.yaml
│   │   ├── 60-ingress.yaml
│   │   └── kustomization.yaml
│   └── prod
│       ├── 10-secret-db.enc.yaml
│       ├── 20-db-statefulset.yaml
│       ├── 30-secret-app.enc.yaml
│       ├── 40-app-config.yaml
│       ├── 50-app-deployment.yaml
│       ├── 60-ingress.yaml
│       ├── 70-secret-cfapi-token.enc.yaml
│       ├── 80-originissuer.yaml
│       ├── 90-certificate-blaster.yaml
│       └── kustomization.yaml
├── lib
└── package.json

In the infra repo:

fluxgitops/flux-config/
├── .sops.yaml
└── clusters
    └── my-cluster
        ├── blaster
        │   ├── 00-namespace.yaml
        │   ├── 10-namespace-prod.yaml
        │   ├── dev
        │   │   ├── 20-blaster-images-dev.yaml
        │   │   ├── 30-image-automation.yaml
        │   │   ├── kustomization.yaml
        │   │   ├── secrets
        │   │   │   └── blaster-dev-registry.yaml
        │   │   └── source.yaml
        │   ├── kustomization.yaml
        │   └── prod
        │       ├── 20-blaster-images-prod.yaml
        │       ├── 30-image-automation.yaml
        │       ├── kustomization.yaml
        │       ├── secrets
        │       │   └── blaster-prod-registry.yaml
        │       └── source.yaml
        ├── flux-system
        │   ├── gotk-components.yaml
        │   ├── gotk-sync.yaml
        │   ├── kustomization.yaml
        │   └── secrets
        │       ├── blaster-dev-registry.yaml
        │       └── blaster-prod-registry.yaml
        └── kustomization.yaml

Principle:

• App repo: what the app looks like.
• Infra repo: how Flux finds and applies the app manifests.

---

8. Verification checklist

• games/blaster has main, develop and at least one feature/* branch.
• k8s/dev and k8s/prod exist with a kustomization.yaml in each.
• GitLab CI builds images on develop and main and pushes them to the registry.
• fluxgitops/flux-config has a clusters/my-cluster/blaster folder.
• Flux GitRepository and Kustomization for blaster-dev are Ready.
• Merges into develop update blaster-dev.
• Merges into main update blaster.

Once this is true, the repo and branch model for Blaster is configured correctly.