Mastering GitLab CI/CD with Advanced Configuration Techniques

GitLab CI/CD in one sentence#

It’s just code that builds, tests, and ships your other code. Every push. Every merge. Every time you break something.

All of it lives in one file. .gitlab-ci.yml.

What a real pipeline actually looks like#

A lot of the YAML floating around out there reads like someone copied it off Stack Overflow, said a quiet prayer, and hit push. Don’t do that. Here’s how to structure a pipeline you can still maintain six months later.

1
stages:
2
  - build
3
  - test
4
  - deploy
5

6
build_job:
7
  stage: build
8
  script:
9
    - echo "Building the project..."
10

11
test_job:
12
  stage: test
13
  script:
14
    - echo "Running tests..."
15

16
deploy_job:
17
  stage: deploy
18
  script:
19
    - echo "Deploying the project..."

That’s the skeleton. Clean and linear. Each stage is one phase of the pipeline. Jobs in the same stage run in parallel, assuming your runners can take it. Want a faster pipeline? This is the first lever you pull.

Docker FTW#

If you’re not pinning your jobs to Docker images, you’re running CI in hard mode for no reason.

1
image: node:20-alpine
2

3
build_job:
4
  stage: build
5
  script:
6
    - npm ci
7
    - npm run build

Pick the right image and your builds get reproducible and portable. Sometimes even fast. Just don’t use latest. Not unless you enjoy surprise breakages on a Monday morning.

Artifacts and cache: the fuel CI runs on#

Now let’s make things quick.

1
build_job:
2
  stage: build
3
  script:
4
    - npm run build
5
  artifacts:
6
    paths:
7
      - dist/

1
cache:
2
  key: ${CI_COMMIT_REF_SLUG}
3
  paths:
4
    - node_modules/

Modular configs with include#

Once that pipeline file crosses 100 lines, YAML turns into YELL.

So split it up.

1
include:
2
  - local: ".gitlab-ci/build.yml"
3
  - local: ".gitlab-ci/deploy.yml"
4
  - project: "devops/templates"
5
    file: "/shared/test-suite.yml"

Now the config is maintainable, reusable, testable. Like actual code, which is what it is.

Keep secrets in the vault#

This should be obvious. I’ll say it loud anyway, for the folks in the back.

Never hardcode secrets in your YAML.

1
variables:
2
  AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY

Manage these in GitLab’s UI, at the project, group, or instance level. Use protected variables for protected branches. Basic hygiene. Don’t be the person who commits prod_db_password: hunter2.

before_script and after_script: your pipeline’s wrapper#

Need to prep or clean up on every run? These are your hooks.

1
test_job:
2
  stage: test
3
  before_script:
4
    - echo "Setting up..."
5
  script:
6
    - npm test
7
  after_script:
8
    - echo "Tearing down..."

I reach for them to bootstrap test databases, set env vars, pull logs, and rage-log failures. Setup and teardown, the same as you’d write in a test suite.

Smarter pipelines with rules#

Want jobs that fire only when they should? Quit misusing only/except. Use rules like a grown-up.

1
deploy_prod:
2
  stage: deploy
3
  script:
4
    - ./scripts/deploy-prod.sh
5
  rules:
6
    - if: '$CI_COMMIT_BRANCH == "main"'
7
      when: always
8
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
9
      when: never

No more deploying off some typo branch by accident.

Real optimization: dynamic variables and better caching#

You can steer pipeline behavior on the fly with job-level variables.

1
deploy:
2
  stage: deploy
3
  variables:
4
    ENV: "staging"
5
  script:
6
    - ./deploy.sh $ENV

Lean on CI_COMMIT_REF_NAME and the other built-ins to drive environments, image tags, artifact names, whatever you need.

And yes, cache keys matter.

1
cache:
2
  key: "${CI_COMMIT_REF_SLUG}"
3
  paths:
4
    - vendor/

One cache per branch keeps builds fast and stops branches from poisoning each other’s state.

TL;DR: how to not suck at GitLab CI#

• Your .gitlab-ci.yml is real code. Treat it like it
• Use Docker images, not host dependencies
• Cache smartly, artifact deliberately
• Stop repeating yourself. Modularize with include
• Use rules to make the pipeline conditional and intelligent
• Secrets go in the GitLab UI, never in version control
• Optimize for speed, clarity, and safety, in that order

Takeaway#

CI/CD isn’t magic. It’s engineering. And a bad pipeline will quietly eat your hours, your weekends, and whatever’s left of your patience.

So build it right the first time. Start with the basics. Modularize as the thing grows. Automate like your job depends on it, because some days it actually does.

Next step is simple. Open the .gitlab-ci.yml, tear out the duct tape, and make it battle-ready.

And if you’re serious about getting good at this, bookmark GitLab’s CI/CD docs. Then go read them.