1. Map one release from change to production
Choose one application and write down how a small change reaches a user today. Include the repository, review steps, build commands, test data, deployment target and person who approves the release. Mark every step that depends on someone remembering a command or copying a file.
Your starting worksheet should answer five questions: what triggers a build, what evidence permits release, which output is deployed, who can change production and who responds when the release fails. Use actual workflow details rather than a list of tools you hope to adopt.
GitLab represents pipeline work as jobs and stages, with runners executing jobs. The event that starts a pipeline and the dependencies between jobs are separate design decisions. See GitLab’s pipeline documentation.
2. Decide what a release must prove
Define the smallest useful set of checks for the chosen application. These might include a build, unit tests, an integration test against a disposable environment and a check of the deployment configuration. Give each check an owner and a clear failure condition.
Keep a traceable relationship between the source revision and the output that will be deployed. Decide which outputs must be retained, who can download them and how long they are useful. GitLab job artifacts can preserve build outputs and reports; their retention and access need deliberate configuration. Read about job artifacts.
Example acceptance statement
“A release identifies its source revision, passes the agreed checks and deploys the same approved build output to the target environment. A failed required check prevents the release from advancing.”
This is a planning example, not a claim about a client implementation. Adapt it to your deployment model.
3. Separate access from configuration
List the credentials each job needs, the environments it can reach and who can change the pipeline definition. Use the least access needed for that task. Development and production should not silently share an unrestricted credential.
GitLab warns that masking a variable does not prevent malicious pipeline code from obtaining it. Review changes that can access secrets, understand protected-variable behaviour and consider an external secrets system where appropriate. Keep secret values out of repositories, examples, logs and enquiry forms. Check GitLab’s variable security guidance.
Record ownership of runners, patching and secret rotation. A pipeline that only one person can maintain creates an operational dependency even when its execution is automated.
4. Rehearse failure as part of the release
Define who can stop a rollout and the evidence that would trigger recovery. Test those steps in a suitable non-production environment before relying on them. Include what happens if an external service is unavailable or a migration has only partly completed.
A deployment rollback and a database restore solve different problems. Reverting application code may not reverse data changes or restore compatibility. Agree how schema changes, queued work and new writes will be handled rather than assuming that an older build is always safe.
GitLab records deployments and supports deployment retry and rollback workflows, subject to the pipeline and job configuration. Check the behaviour of your own jobs. Read the deployment documentation.
5. Leave an operator with a usable runbook
Ask someone other than the pipeline author to follow the runbook during a controlled exercise. They should be able to find a failed job, identify the deployed version, locate relevant logs and contact the right owner. Record any step that needs undocumented knowledge.
- A named owner for the application, pipeline and runtime environment.
- Agreed build outputs, required checks and release approval rules.
- Documented access boundaries and a secret-rotation owner.
- A rehearsed recovery path, including data-change limitations.
- Alert routing, operating notes and an agreed follow-up backlog.
Bring this worksheet, a simple environment diagram and your main release bottlenecks to a scoping conversation. Agree the first application and acceptance checks before expanding automation across the estate.