# ---- 1. The file -----------------------------------------------------------
# When you push a commit, GitLab looks for a file named .gitlab-ci.yml at the
# root of your repository. What it finds there becomes a PIPELINE: a set of
# JOBS, each a small script that runs on a machine GitLab controls, called a
# RUNNER. A few top-level keys in this file are settings for the whole
# pipeline. Every other top-level key is the name of a job.

# `spec` is optional, and if you use it, it has to be the very first thing in
# the file, in its own YAML document that ends with a line of three dashes.
spec:
  # "Inputs" are values that whoever starts the pipeline can choose, like the
  # arguments of a function. Use them for the few things that change from one
  # run to the next, such as which environment to deploy to. GitLab fills
  # them in while it is reading this file, before any job exists, so an input
  # can't hold something that is only known later, like a build number.
  inputs:
    greeting:
      default: "hello"              # the value used when nobody chooses one
      description: "What the jobs say"   # shown next to the field
      type: string                  # or number, boolean, array
      options: ["hello", "hi"]      # the only values allowed
      # regex: ^h                   # or a pattern the value must match
---
# The STAGES, in order. A stage is a step of the pipeline, such as "build" or
# "test". Every job belongs to one stage, and a stage starts only when every
# job in the stage before it has passed. That is how you say "test after
# building". Two stages always exist without being listed: `.pre` runs first
# and `.post` runs last.
stages:
  - build
  - test
  - package
  - deploy

# `default` holds settings that every job gets, unless a job sets its own.
# Put here what you would otherwise repeat in every job. (Older files put
# `image:` or `before_script:` directly at the top level instead; that is the
# old way of writing the same thing.)
default:
  # Every job runs inside a CONTAINER: a fresh, throwaway Linux box. The IMAGE
  # is the snapshot that box starts from, with the tools already installed.
  # Always pin it to a version, so that the job behaves the same next month.
  image: alpine:3.22
  # Commands that run before the job's own script, in the same shell. Use it
  # for setup that every job needs, such as logging in.
  before_script:
    - echo "before_script runs first, in every job"
  # Commands that run after the script, in a separate shell, even when the
  # script failed. Use it for clean-up, or for saving a report of a failure.
  after_script:
    - echo "after_script runs last, even when the script failed"
  # If a newer commit is pushed while this job is waiting or running, GitLab
  # may cancel it, because the newer pipeline will run it again anyway.
  interruptible: true
  # Run the job again if it fails: at most once, and only when the runner
  # itself broke, not when the script returned an error. Retrying on every
  # failure would hide real bugs.
  retry:
    max: 1
    when: [runner_system_failure]
    # exit_codes: [137]              # or only for these exit codes

# Here is a job. Its name is the key, and you choose it. `stage` says when it
# runs, and `script` is the list of shell commands it runs, one after the
# other, in a fresh container that holds a fresh copy of the repository. If
# any command fails, the job fails.
say-hello:
  stage: build
  # Stop the job, as failed, if it runs longer than this. `timeout` is set per
  # job; it is one of the few settings `default` can't hold.
  timeout: 10m
  script:
    # An input from `spec` above, filled in while the file was being read.
    - echo "$[[ inputs.greeting ]] from a job"
    # VARIABLES are named values a job can read, written as $NAME. GitLab
    # sets these two, and many more, for every job: they are called
    # predefined variables. SHORT_SHA is the commit's id, and REF_NAME the
    # branch or tag.
    - echo "commit $CI_COMMIT_SHORT_SHA on $CI_COMMIT_REF_NAME"

# ---- 2. Reuse: where most of a real pipeline comes from --------------------
# In a large organisation, your file is short, because most of your jobs are
# written once by a central team and copied into your pipeline. This part
# shows every way of copying, and when to use which:
#   include     brings whole FILES into this one, as if pasted here.
#   extends     copies a whole JOB (a template job) into one of yours.
#   !reference  copies one SECTION of a job, such as its list of commands.
#   an anchor   copies a piece of YAML, but only inside the same file.

# `include` pulls other YAML files into this one. GitLab reads them first,
# and joins everything into one big configuration, as if you had pasted the
# files here. Jobs in those files become your jobs, and template jobs in
# them become available to `extends` and `!reference` below.
include:
  # `local`: a file in this same repository, at the same commit.
  - local: ci/base.yml
    # An include can carry `rules`: conditions that say when to include the
    # file at all. This one says: only if the file exists.
    rules:
      - exists: [ci/base.yml]
  # `project`: a file in another GitLab project. This is how a central team
  # shares its templates. `ref` pins a tag or commit, so that the central
  # team's next change can't alter your pipeline until you choose it.
  - project: practice/central-templates
    ref: 1.0.0
    file: templates/node.yml
  # `component`: a packaged, versioned job with typed inputs, published by a
  # project. It differs from a plain `project` include in that you set its
  # inputs here, and GitLab checks them. The address is the GitLab server,
  # the project, the component's name, and its version after the @.
  - component: $CI_SERVER_FQDN/practice/central-templates/secret-scan@1.0.0
    inputs:
      stage: test
  # `template`: a file that GitLab itself ships, such as its scanners:
  # - template: Jobs/Build.gitlab-ci.yml
  # `remote`: a file at any URL. `integrity` pins its checksum, so that a
  # changed file is refused:
  # - remote: https://example.com/ci.yml
  #   integrity: sha256-L5/GAbeXGkPeEtIuOJhiJP+5xgrgdlwFEqm1O3EJwHM=
#
# What an expert knows about includes: GitLab joins the files in the order
# listed, and if two files define a job of the same name, the later one wins.
# Your own file is joined last, so it beats them all. To see the joined
# result, open Build > Pipeline editor > Full configuration: that view shows
# every job with its includes, `extends` and `!reference` already resolved,
# and it is where you trace any job you did not write.

# A YAML ANCHOR is plain YAML, not a GitLab feature: `&login` gives this list
# a name, and `*login` further down pastes a copy of it. Anchors are the
# oldest way of avoiding repetition, and you will meet them in older files.
# Their limit: an anchor only works inside the one file it is written in. It
# can't reach anything that came in through `include`. The two GitLab
# keywords below can, which is why they replaced anchors.
.login: &login
  - echo "logging in"

# A job whose name starts with a dot is HIDDEN: GitLab never runs it. Hidden
# jobs exist to be copied. `.base-build` is one, written in ci/base.yml.
#
# `extends` copies a hidden job into this job, and then lays this job's own
# settings on top. Use it when a central team has written the job you need
# and you want to change one or two things. How the two are combined:
#   - settings that are maps, such as `variables` and `cache`, are merged
#     key by key, so you can add or change one key and keep the rest;
#   - settings that are lists, such as `script`, `rules`, `before_script`,
#     `tags` and `services`, are replaced whole: if you write one line of
#     `script`, the template's whole script is gone.
# Experts also know: `extends` can chain, a job extending a job that extends
# another, across files, and GitLab advises three levels at most. To trace a
# chain, search the included files for each parent's name, one hop at a time.
build:
  extends: .base-build
  stage: build
  # The anchor from above, pasted in. It works because both are in this file.
  before_script: *login
  script:
    # `!reference` copies ONE section of another job, from any file, and
    # pastes it exactly here. Compare it with `extends`: `extends` takes a
    # whole job and merges it underneath yours; `!reference` takes one piece
    # and puts it where you say. Use it to keep a template's list and add
    # your own lines around it, which `extends` can't do for lists. Here it
    # pastes the `make` list from `.snippets` in ci/base.yml.
    - !reference [.snippets, make]
    - echo "built at $CI_COMMIT_SHORT_SHA" > build.txt
  # ARTIFACTS are files GitLab keeps when the job ends and hands to later
  # jobs. Without this, build.txt would vanish with the container. Part 5
  # shows all the settings.
  artifacts:
    paths: [build.txt]

# `parallel: matrix` turns one job into several, one per combination of the
# values, each with the variable set. GitLab names them "test: [unit]" and
# "test: [integration]". Use it to run the same job for several versions,
# platforms or suites without copying the job.
test:
  stage: test
  parallel:
    matrix:
      - SUITE: [unit, integration]
  script:
    - echo "running the $SUITE tests"

# A TRIGGER job has no script. It starts another pipeline and reports how that
# went. With `include`, the other pipeline is a CHILD: it is described by
# another file in this repository and shown nested inside this pipeline.
# Use a child pipeline to keep a big pipeline in several files, or to
# generate a pipeline from a script.
child:
  stage: test
  trigger:
    include:
      - local: ci/child.yml
        # The child file has a `spec` with inputs of its own, filled in here.
        inputs:
          who: "the parent pipeline"
    # `mirror` makes this job show the child's status: it waits for the child
    # and fails if the child fails. Without it, the job passes the moment the
    # child is created, whatever happens afterwards, so a broken child would
    # show green. Older files say `strategy: depend`, which GitLab no longer
    # recommends.
    strategy: mirror
    # Pass this pipeline's variables down to the child.
    forward:
      pipeline_variables: true
  # The other kind of trigger: with `project`, GitLab runs ANOTHER PROJECT's
  # own pipeline, called a multi-project pipeline. Use it to kick off a
  # deploy repository, for example. Its inputs go under `trigger:` itself:
  # trigger:
  #   project: practice/node-service
  #   inputs: { who: "another project" }

# A job whose name starts with a dot is HIDDEN: GitLab never runs it. It is a
# template, written so that other jobs can copy it with `extends`. This one
# lives in a separate file, which .gitlab-ci.yml brings in with `include`.
# A YAML anchor could never reach it from there; `extends` can.
.base-build:
  image: alpine:3.22
  cache:
    key: base
    paths: [.cache/]
    policy: pull

# A hidden job can also hold keys that are not CI/CD keywords at all, like
# `make` here. They are snippets: pieces of YAML kept in one place, for jobs
# to paste with `!reference [.snippets, make]`. Central teams keep their
# shared script lines and rule lists this way.
.snippets:
  make:
    - echo "a make step, pasted from ci/base.yml with !reference"

# A child pipeline is a complete pipeline of its own, described by this file
# and shown nested inside the pipeline that triggered it. It has its own
# `spec`, so the parent can pass it inputs.
spec:
  inputs:
    who:
      default: "nobody"          # the parent's trigger fills this in
---
child-job:
  image: alpine:3.22
  # Inside a child, $CI_PIPELINE_SOURCE is "parent_pipeline". A job with no
  # rules runs only for branches and tags, and a merge request's pipeline is
  # neither, so without this rule the child would have no jobs there, and
  # GitLab would refuse to create it.
  rules:
    - if: $CI_PIPELINE_SOURCE == "parent_pipeline"
  script:
    - echo "hello from $[[ inputs.who ]], in a child pipeline"
    # The parent's `forward: pipeline_variables` passed its variables down.
    - echo "the parent forwarded LOG_LEVEL=$LOG_LEVEL"

# ---- 3. Conditions: which pipelines exist, and which jobs are in them ------
# GitLab decides twice. First, does this push get a pipeline at all? That is
# `workflow`. Then, for every job, is it in this pipeline? That is the job's
# `rules`. Both are lists of conditions that GitLab tries from the top, and
# the first one that matches decides. Nothing else is looked at.
#
# The conditions use predefined variables. The ones you will see most:
#   $CI_PIPELINE_SOURCE   what caused the pipeline: "push", "schedule",
#                         "merge_request_event", "web" and others
#   $CI_COMMIT_BRANCH     the branch name, set only in a branch pipeline
#   $CI_COMMIT_TAG        the tag name, set only in a tag pipeline
#   $CI_OPEN_MERGE_REQUESTS   set when the branch has an open merge request
#
# The pattern experts use: put the cases to exclude first, each with
# `when: never`, then the cases to allow, and let everything else fall off
# the end, which means no pipeline. A workflow decides only whether the
# pipeline exists; it can't put a job in or out.
workflow:
  # The pipeline's title in the pipeline list. Variables are filled in.
  name: "$KIND pipeline for $CI_COMMIT_REF_NAME"
  # When a newer commit is pushed, cancel the older pipeline's jobs that are
  # marked `interruptible`, since the newer pipeline covers them.
  auto_cancel:
    on_new_commit: interruptible
    # on_job_failure: all           # or cancel everything when one job fails
  rules:
    # A MERGE REQUEST is a request to merge one branch into another, with a
    # review. GitLab can run a pipeline for the merge request itself, and
    # show the result on it. This rule says: create that pipeline.
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      variables:
        # A rule can also set a variable for the whole pipeline.
        KIND: "merge request"
    # A push to a branch normally gets a branch pipeline too. While a merge
    # request is open for that branch, the merge request pipeline already
    # covers the push, so don't make a second one. Without this rule, every
    # push would run everything twice.
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    # Any other push to a branch: create the pipeline.
    - if: $CI_COMMIT_BRANCH
      variables:
        KIND: "branch"              # every job can read KIND
    # A push of a tag: create the pipeline. Anything not matched here, such
    # as a schedule, gets no pipeline.
    - if: $CI_COMMIT_TAG
      variables:
        KIND: "tag"

# A job's `rules` decide whether the job is part of this pipeline, and how it
# runs. The first rule that matches decides. If no rule matches, the job is
# simply left out, with no message anywhere: that is the most common reason a
# job "didn't run". Order the rules from the most specific case to the most
# general, and put `when: never` rules first to exclude cases. A job can't mix
# `rules` with the older `only`/`except`. To see which jobs a push would get
# before pushing, use Build > Pipeline editor > Validate.
lint:
  stage: test
  script: echo "lint, in $LINT_MODE mode"
  rules:
    # `if` tests variables. This one says: always, on the default branch
    # (usually main).
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      variables:
        LINT_MODE: "full"           # a rule can set a variable for this job
    # `changes` tests which files the commit changed. Only if a file under
    # src/ changed does this rule match. Two surprises: on the first push of
    # a new branch it is always true, and in a merge request pipeline it
    # compares against the target branch, not the previous commit.
    - changes:
        paths: [src/**/*]
        # regexp: src/.*\.js$       # or a Ruby regular expression instead
        compare_to: refs/heads/main
      variables:
        LINT_MODE: "changed-files"  # a different value from a different rule
    # Before `rules` existed, jobs used `only:` and `except:` for the same
    # purpose. Older templates still have them; they mean "only in these
    # cases" and "except in these cases".

# A MANUAL job is a play button: it sits in the pipeline until a person
# starts it. Two things to know. A manual job that a rule adds counts as
# "not finished", so the pipeline shows as blocked until someone runs it,
# unless the rule also says `allow_failure: true`, as here. And a job that
# `needs` a manual job is skipped until the manual job has been run.
approve-docs:
  stage: test
  script: echo "the docs were approved by hand"
  rules:
    # `exists` tests whether a file is in the repository at all.
    - exists: [docs/notes.md]
      when: manual
      allow_failure: true

# By default a job waits for the whole previous stage. `needs` lists the jobs
# this one really depends on, and the job starts as soon as those have
# finished, whatever their stage. It also downloads their artifacts. Use it
# to make pipelines faster. A job may need jobs from earlier stages or its
# own; a job that needs a job that isn't in the pipeline fails to be created,
# unless the need is `optional`.
package:
  stage: package
  needs:
    - job: build
    # One instance of a matrix job. `artifacts: false` means: wait for it,
    # but don't download its files.
    - job: test
      parallel:
        matrix:
          - SUITE: unit
      artifacts: false
    # `optional` means: if this job isn't in the pipeline at all, as on a
    # branch where lint's rules didn't match, don't wait for it.
    - job: lint
      optional: true
    # Premium: a job in another project's pipeline.
    # - project: group/other
    #   job: build
    #   ref: main
    #   artifacts: true
  script:
    - cat build.txt
    - echo "this is a $KIND pipeline"

# `when` says under what condition a job runs, once it is in the pipeline:
#   on_success   when no job in an earlier stage failed (the default)
#   on_failure   only when a job in an earlier stage failed
#   always       whatever happened earlier
#   never        not at all
#   manual       when a person presses play
#   delayed      after a wait
cleanup:
  stage: .post
  when: always
  # `dependencies` chooses which earlier jobs' artifacts to download. By
  # default a job downloads all of them. An empty list downloads none, which
  # makes a job like this faster.
  dependencies: []
  script: echo "cleanup"

# A DELAYED job waits for a set time after its stage is ready, then starts on
# its own, unless someone cancels it. Use it for a pause before a rollout.
warm-up:
  stage: deploy
  when: delayed
  # How long to wait before starting.
  start_in: 10 seconds
  script: echo "warmed up"

# ---- 4. What a job is given: variables, secrets and identity ---------------
# A job can read values from several places, and when two places set the
# same name, the higher one on this ladder wins:
#   1. a security policy (set by a security team, outside any file)
#   2. values given when the pipeline was started by hand or by a trigger
#   3. the project's settings page, then its groups', then the instance's
#   4. dotenv reports from earlier jobs (part 5)
#   5. the job's own `variables`
#   6. the top-level `variables` below
#   7. GitLab's predefined variables
# The most common surprise: a value set on a settings page (3) silently beats
# the value you wrote in the file (5 or 6). When a value isn't what you wrote,
# check Settings > CI/CD > Variables on the project, then on each of its
# groups, then ask about the instance: the job's page does not show them.
#
# Top-level `variables` reach every job.
variables:
  APP: "in-45-minutes"          # the plain form: a name and a value
  # The long form, with a description and a list of allowed values. GitLab
  # then shows the variable as a field on its "Run pipeline" page.
  LOG_LEVEL:
    value: "info"
    description: "How much the jobs print"
    options: ["info", "debug"]
  # Normally a `$` inside a value refers to another variable. `expand: false`
  # keeps the `$` as plain text.
  RAW_VALUE:
    value: "$APP-literal"
    expand: false

show-variables:
  stage: build
  # The job's own `variables` win over the top-level ones (5 beats 6). A value
  # that came in through `extends` counts as the job's own.
  variables:
    LOG_LEVEL: "debug"
  # `inherit` limits what this job takes from `default:` and from the
  # top-level `variables`. Here it takes only `image`, and only these three
  # variables. The workflow's KIND is not in the list, so this job can't see
  # it. Use `inherit` for a job that must be isolated from the rest.
  inherit:
    default: [image]
    variables: [APP, LOG_LEVEL, RAW_VALUE]
  # An ID TOKEN is a short-lived, signed statement from GitLab that says which
  # project, branch and job this is. A cloud such as AWS or Azure can be set
  # up to trust it, and give the job access, so that no long-lived password
  # or key has to be stored anywhere. `aud` (audience) is who the token is
  # meant for.
  id_tokens:
    CLOUD_TOKEN:
      aud: https://cloud.example.com
  script:
    - echo "APP=$APP LOG_LEVEL=$LOG_LEVEL RAW_VALUE=$RAW_VALUE KIND=$KIND"
    - test -n "$CLOUD_TOKEN" && echo "an ID token was issued for this job"
    # DEPLOY_TOKEN is not in this file at all. It was typed into the project's
    # settings page (rung 3 of the ladder), which is where secrets belong.
    # There it was marked MASKED, so a log shows [MASKED] instead of the
    # value, and PROTECTED, so only pipelines on protected branches and tags,
    # such as main, receive it. On any other branch it is simply empty, which
    # is why a job can work on main and fail on a feature branch. GitLab can
    # only mask a value that is one line, without spaces, and at least eight
    # characters long; anything else it refuses to mask.
    - echo "DEPLOY_TOKEN=$DEPLOY_TOKEN"
  # Premium: `secrets` fetches a value at run time from an outside store, and
  # by default writes it to a file whose path is in the variable.
  # secrets:
  #   DB_PASSWORD:
  #     vault: kv/db/password@secret
  #     file: false                  # the value in the variable, not a file
  #     token: $CLOUD_TOKEN          # which ID token to present to the store
  #   API_KEY:
  #     aws_secrets_manager: { secret_id: api-key }
  #   CERT:
  #     azure_key_vault: { name: cert }
  #   DSN:
  #     gcp_secret_manager: { name: dsn, version: latest }
  #   PEPPER:
  #     gitlab_secrets_manager: { name: pepper }
  # Sign the job in to Google Cloud with its ID token (GitLab.com only, beta):
  # identity: google_cloud

# ---- 5. Execution and data: where a job runs, and what it passes on --------
with-service:
  stage: test
  # `image` in its long form. `name` is the image; the other keys adjust how
  # it is used.
  image:
    name: alpine:3.22
    # An image can have a default command, its ENTRYPOINT. A tool's own image
    # often makes that the tool itself, and then your script never runs.
    # An empty entrypoint switches that off.
    entrypoint: [""]
    # Reuse an already downloaded copy of the image instead of pulling it
    # again every time.
    pull_policy: if-not-present
    # Docker-only settings, such as the platform:
    # docker: { platform: linux/amd64 }
  # A SERVICE is a second container started beside the job, for something the
  # job needs to talk to, such as a database. The job reaches it by the
  # `alias` as a host name. Here it is a small registry, reached as "reg".
  # A service must stay running on its own; when a job can't reach one, read
  # the service's own log, which the job page shows separately.
  services:
    - name: registry:2
      alias: reg
      variables:
        REGISTRY_LOG_LEVEL: "warn"   # set inside the service container only
  # `tags` sends the job only to runners that carry the same tag, for example
  # a runner with a GPU or one inside a private network. If no online runner
  # has the tag, the job waits forever.
  # tags: [linux]
  # `hooks` runs commands at fixed points of the job's life. This one runs
  # before the repository is even fetched, for example to set up Git access.
  hooks:
    pre_get_sources_script:
      - echo "about to clone"
  variables:
    # GIT_DEPTH controls how much history the job fetches. Jobs get a shallow
    # copy of their own branch only, which is fast, but a script that reads
    # older commits or tags finds nothing there.
    GIT_DEPTH: "5"
  script:
    - wget -qO- http://reg:5000/v2/ && echo "the service answered"
    - echo "coverage lines 87.5%"
  # `coverage` is a pattern GitLab searches the log with. The number it finds
  # becomes the job's test coverage, shown in badges and merge requests.
  coverage: '/coverage lines (\d+\.\d+)%/'

keep-files:
  stage: package
  # An empty `needs` means: depend on nothing, start at once.
  needs: []
  script:
    - mkdir -p out && echo "a report" > out/report.txt
    # A DOTENV file is a text file of NAME=value lines. Reported as an
    # artifact (below), its lines become variables in every later job.
    - echo "VERSION=1.4.0" > build.env
  # ARTIFACTS, in full. Files GitLab uploads when the job ends, keeps for a
  # while, and gives to later jobs. They are guaranteed to arrive, which is
  # what makes them different from the cache further down.
  artifacts:
    # The name of the download, as shown on the job page.
    name: "$CI_JOB_NAME-$CI_COMMIT_SHORT_SHA"
    # Which files and folders to keep.
    paths: [out/]
    # Which of those to leave out.
    exclude: [out/**/*.tmp]
    # How long GitLab keeps them before deleting them. Without it, the
    # instance's default applies.
    expire_in: 1 week
    # Keep the files even when the job failed: that is when you need them.
    when: always
    # Show a link to them on the merge request.
    expose_as: "report"
    # Who may download them from GitLab: all, developer, maintainer or none.
    # The older `public: false` means the same as `developer`.
    access: developer
    # REPORTS are artifacts in a format GitLab understands and shows: test
    # results (junit), coverage, security findings, and dotenv for variables.
    reports:
      dotenv: build.env
  # The CACHE is for speed, and nothing else. It keeps files such as
  # downloaded packages between pipelines, so the next job doesn't download
  # them again.
  # Unlike artifacts, a cache is not guaranteed: it may be missing on another
  # runner or after a clean-up, so a job must still work without it. The
  # first pipeline after a key changes always finds nothing, and caches of
  # protected branches are kept apart from the rest (the key gets a
  # "-protected" suffix) unless `unprotect` says otherwise.
  cache:
    # The key names the cache. `files` makes the key change when these files
    # change, so a changed dependency list never restores a stale cache.
    key:
      files: [ci/base.yml]
      # files_commits: [ci/base.yml]   # or the files' last commits instead
      prefix: "$CI_JOB_NAME"
    # Which folders to keep. They must be inside the project's folder.
    paths: [.cache/]
    # `pull` restores the cache, `push` saves it, `pull-push` does both.
    policy: pull-push
    # Save the cache only when the job passed (or `always`, or `on_failure`).
    when: on_success
    # Other keys to try when this one has no cache yet.
    fallback_keys: [default]
    # Caches of protected branches are normally kept apart. This shares them.
    unprotect: true
    # `true` would also cache every file Git doesn't track, such as build
    # output.
    untracked: false

use-files:
  stage: deploy
  needs: [keep-files]
  # A RESOURCE GROUP lets only one job of the group run at a time, even across
  # pipelines. Use it so that two deploys to the same place never overlap.
  resource_group: staging
  script:
    # out/report.txt arrived as an artifact, and VERSION from the dotenv.
    - cat out/report.txt
    - echo "VERSION=$VERSION, from the dotenv report"

# ---- 7. After the pipeline: deploys, environments and releases -------------
# An ENVIRONMENT is a place your software runs, such as staging or production.
# A job that names one is a deploy job, and GitLab records every run of it:
# which commit went where, and when. That record is what "Operate >
# Environments" shows, and its Rollback button reruns an earlier deploy job
# with that older commit, which is the quickest way back.
deploy-staging:
  stage: deploy
  script:
    # Deploy the image this pipeline built, tagged with the commit, and deploy
    # that same tag everywhere. A pipeline that builds a fresh image for each
    # environment ships something nobody tested.
    - echo "deploying $APP:$CI_COMMIT_SHORT_SHA to staging"
  environment:
    name: staging
    # A link to the running service, shown beside the environment.
    url: https://staging.example.com
    # What kind of environment this is: production, staging, testing,
    # development or other. GitLab groups and reports them by tier.
    deployment_tier: staging
    # The job that tears the environment down, and when to run it on its own.
    on_stop: stop-staging
    auto_stop_in: 1 day
    # Which agent for Kubernetes and which namespace the environment's
    # dashboard shows. (`kubernetes: namespace:` on its own is the old form.)
    # kubernetes:
    #   agent: platform/agents:staging
    #   dashboard: { namespace: staging }
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# The stop job named above. `action: stop` tells GitLab that this job ends the
# environment rather than deploying to it.
stop-staging:
  stage: deploy
  script: echo "stopping staging"
  environment:
    name: staging
    action: stop
  when: manual
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy-production:
  stage: deploy
  script:
    # Many organisations deploy with GITOPS: the job doesn't touch the cluster
    # at all. It writes the new image tag into a Git repository that describes
    # the environment, and a controller running in the cluster notices the
    # change and applies it, minutes later. So a green job here means
    # "written to Git", not "running". To know whether the change is really
    # running, look at the controller, Argo CD or Flux, and at the pods, not
    # at this job.
    - echo "writing tag $CI_COMMIT_SHORT_SHA to the environment repository"
  environment:
    name: production
    url: https://example.com
  # Production waits for a person: `manual` gives the job a play button, and
  # `manual_confirmation` adds a box with this text that must be confirmed
  # before the job starts.
  when: manual
  manual_confirmation: "Deploy to production?"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# A RELEASE is GitLab's record of a version: a tag with a title, notes and
# download links, shown under "Deploy > Releases". A job with `release:` in a
# tag pipeline creates it. The job needs GitLab's `glab` command in its image
# (registry.gitlab.com/gitlab-org/cli), so it stays a comment here.
# release:
#   stage: deploy
#   script: echo "releasing $CI_COMMIT_TAG"
#   release:
#     tag_name: $CI_COMMIT_TAG
#     tag_message: "Version $CI_COMMIT_TAG"
#     name: "Release $CI_COMMIT_TAG"
#     description: "Built from $CI_COMMIT_SHORT_SHA"
#     milestones: ["1.4"]
#     released_at: "2026-09-26T09:00:00Z"
#     assets:
#       links: [{ name: "binary", url: "https://example.com/app.tar.gz" }]
#   rules:
#     - if: $CI_COMMIT_TAG

# GITLAB PAGES hosts static websites straight from a repository. A job with
# `pages: true` publishes its `public/` folder as the site; naming the job
# `pages` used to be what did it, and is now deprecated. Pages is switched
# off on this GitLab, so it stays a comment too.
# publish-site:
#   stage: deploy
#   script: mkdir -p public && echo "hello" > public/index.html
#   pages: true
#   artifacts:
#     paths: [public/]

include:
  - project: megacorp/devops/ci-templates
    ref: v4.2.0
    file: pipelines/java-service.yml
  - component: $CI_SERVER_FQDN/megacorp/devops/components/sonar-scan@2.1.0
    inputs:
      stage: test
      project_key: payments-api

include:
  - project: megacorp/devops/ci-templates
    ref: v4.2.0
    file:
      - templates/base.yml
      - templates/snippets.yml
      - templates/rules.yml
      - templates/workflow.yml
      - templates/java-maven.yml
      - templates/container.yml
      - templates/security.yml
      - templates/deploy.yml

maven-build:
  extends: .maven-build

maven-test:
  extends: .maven-test

image-build:
  extends: .image-build
  needs: [maven-build]

# Every project under megacorp/ receives these. A group variable takes precedence
# over any variable of the same name in a project's .gitlab-ci.yml.
group_variables:
  - key: MAVEN_CLI_OPTS
    value: "--batch-mode --errors --show-version -s .m2/settings.xml"
  - key: AWS_ACCOUNT_ID
    value: "123456789012"
  - key: MC_AZURE_TENANT_ID
    value: "00000000-0000-0000-0000-000000000000"
  - key: MC_ACR_REGISTRY
    value: megacorpprod.azurecr.io
  - key: MC_ACR_PUSH_CLIENT_ID
    value: "00000000-0000-0000-0000-000000000000"
    # the gitlab-acr-push application in Entra ID, which mc_acr_push signs in as
  - key: SONAR_HOST_URL
    value: https://sonar.example.com
  - key: SONAR_TOKEN
    value: "(set in the UI)"
    masked: true
    protected: true

secret-check:
  stage: test
  script:
    - echo "DEPLOY_TOKEN is '$DEPLOY_TOKEN'"

terraform {
  required_version = ">= 1.12"
  backend "http" {}
  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "3.9.1"
    }
  }
}

variable "team" {
  type    = string
  default = "payments"
}

resource "random_pet" "queue" {
  prefix = var.team
  length = 2
}

output "queue_name" {
  value = random_pet.queue.id
}

variables:
  TF_STATE_NAME: default
  TF_HTTP_ADDRESS: $CI_API_V4_URL/projects/$CI_PROJECT_ID/terraform/state/$TF_STATE_NAME
  TF_HTTP_LOCK_ADDRESS: $CI_API_V4_URL/projects/$CI_PROJECT_ID/terraform/state/$TF_STATE_NAME/lock
  TF_HTTP_UNLOCK_ADDRESS: $CI_API_V4_URL/projects/$CI_PROJECT_ID/terraform/state/$TF_STATE_NAME/lock
  TF_HTTP_LOCK_METHOD: POST
  TF_HTTP_UNLOCK_METHOD: DELETE
  TF_HTTP_USERNAME: gitlab-ci-token
  TF_HTTP_PASSWORD: $CI_JOB_TOKEN

default:
  image:
    name: ghcr.io/opentofu/opentofu:1.12.6
    entrypoint: [""]
  before_script:
    - tofu init -input=false

validate:
  stage: validate
  script:
    - tofu fmt -check
    - tofu validate
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

plan:
  stage: plan
  script:
    - apk add --no-cache jq
    - tofu plan -input=false -out=plan.cache
    - tofu show -json plan.cache | jq -r '([.resource_changes[]?.change.actions?]|flatten)|{"create":(map(select(.=="create"))|length),"update":(map(select(.=="update"))|length),"delete":(map(select(.=="delete"))|length)}' > plan.json
  artifacts:
    paths:
      - plan.cache
    reports:
      terraform: plan.json
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

apply:
  stage: apply
  script:
    - tofu apply -input=false plan.cache
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

spec:
  inputs:
    stage:
      default: test
    paths:
      default: "."
      description: The directory to look in

secret-scan:
  stage: $[[ inputs.stage ]]
  image: alpine:3.22
  script:
    - echo "Looking for private keys in $[[ inputs.paths ]]"
    - if grep -rl "BEGIN [A-Z ]*PRIVATE KEY" $[[ inputs.paths ]]; then echo "A private key is committed"; exit 1; fi
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH

include:
  - project: megacorp/devops/ci-templates
    ref: v4.2.0
    file: pipelines/java-service.yml
  - component: $CI_SERVER_FQDN/megacorp/devops/components/sonar-scan@2.1.0
    inputs:
      stage: test
      project_key: payments-api

.defaults: &defaults
  image: registry.example.com/megacorp/devops/ci-tools:2.9
  tags: [megacorp-shared]
  only:
    - branches
    - tags

build:
  <<: *defaults
  stage: build
  script:
    - ./gradlew assemble

.megacorp-base:
  variables:
    MC_TEAM: unknown
  artifacts:
    expire_in: 7 days
  rules:
    - !reference [.rules, never-on-schedule]
    - !reference [.rules, mr]
    - !reference [.rules, default-branch]
    - !reference [.rules, release-tag]

.maven-base:
  extends: .megacorp-base
  image: registry.example.com/megacorp/devops/ci-tools/maven:3.9-jdk${JAVA_VERSION}
  variables:
    JAVA_VERSION: "21"
    MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository"
  cache:
    key:
      files: [pom.xml]
    paths: [.m2/repository]
  before_script:
    # a job's own before_script replaces default:before_script, so re-add the functions
    - !reference [.snippets, functions]
    - !reference [.snippets, maven_settings]

.snippets:
  functions:
    - source /opt/megacorp/lib/ci-lib.sh
  aws_login:
    - mc_aws_login "$AWS_ROLE_ARN"
  acr_push:
    - mc_acr_push "$IMAGE:$CI_COMMIT_SHA"
  maven_settings:
    - mkdir -p .m2
    - mc_maven_settings > .m2/settings.xml

.rules:
  mr:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  default-branch:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  release-tag:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
  never-on-schedule:
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: never

default:
  image: registry.example.com/megacorp/devops/ci-tools:3.2
  tags: [megacorp-shared]
  interruptible: true
  retry:
    max: 2
    when: [runner_system_failure, stuck_or_timeout_failure]
  before_script:
    - !reference [.snippets, functions]
    - mc_log "job $CI_JOB_NAME on $CI_COMMIT_REF_NAME"

publish-docs:
  stage: deploy
  image: registry.example.com/megacorp/devops/ci-tools/docs:1.4
  inherit:
    default: [tags, retry]
    variables: false
  script:
    - mkdocs build --strict
  rules:
    - !reference [.rules, default-branch]

variables:
  GIT_DEPTH: "20"
  AWS_REGION: eu-west-2
  MC_TEMPLATES_VERSION: "4.2.0"

variables:
  JAVA_VERSION: "21"
  MC_TEAM: payments

.megacorp-base:
  variables:
    MC_TEAM: unknown
  artifacts:
    expire_in: 7 days
  rules:
    - !reference [.rules, never-on-schedule]
    - !reference [.rules, mr]
    - !reference [.rules, default-branch]
    - !reference [.rules, release-tag]