Branches and merge requests
The trigger for a deployment is main; whether you push directly or merge feature branches through merge requests is your team’s decision. Feature branches run through the pipeline with dynamic build versions, but without a version commit or deployment.
git checkout main
git pull
git add .
git commit -m "feat: persist shopping cart"
git push
Pull the current state of main before you push, because the pipeline creates version commits there itself. The pre-commit hook ap git pre-commit check from the setup app and ap platform projects clone blocks commits to .gitlab-ci.yml and env/*.generated.env; ap git auto-commit handles staging, commit and push in one step.
The pipeline on main
flowchart LR test["test"] --> version["update-version"] version --> build["build"] build -->|"automatic"| publish["publish: dev"] publish -->|"manual job"| release["release: prod"]
test runs tests and checks, update-version derives the next version following Conventional Commits (feat: raises the minor version, fix: the patch version), and build produces the Docker image or the app build with that version. publish records the state in configurations/dev/versions.yaml of gitops-configuration, after which the dev server pulls the version; for apps, publish means TestFlight and the internal track on Google Play. release is the manual job for production or the store submission. Every job has a log in GitLab under CI/CD → Pipelines, the first place to look when a pipeline turns red.
Releasing production
Production receives exactly the build that already runs on dev. In GitLab, open the pipeline of the main state you want to roll out under CI/CD → Pipelines and start the production job via the play button; the pipeline writes the version into configurations/prod/versions.yaml, and the prod server pulls it. There is no further confirmation step between release and going live, so verify the change on dev beforehand.
You maintain your own environment variables for dev or prod in gitops-configuration/configurations/<env>/custom.yaml; a commit to main in that repository rolls the change out without building a new image. Environment variables describes the files.
Returning to an earlier state
Because every pipeline keeps its build, a rollback is the same click as a release: open the pipeline of the last working main state and start its production job again. Which version runs where is recorded in the versions.yaml of each environment; Sentry links errors to the same release version once a Sentry account is connected under Connections. How to keep an eye on errors and servers after a release is covered in Operations.