Skip to content

GitLab CI structure

This documentation details how the default pipelines have been organized.

They are all about testing, building, and deploying the Kamea project.

Files structure example

.gitlab-ci.yml # Main GitLab file
    ├──   core/apps/azure-functions/.gitlab-ci.yml        # specific project CI
    ├──   infrastructure/.gitlab-ci.yml                   # specific project CI
    ├──   website/.gitlab-ci.yml                          # specific project CI

Main GitLab file

In this file we defined all static configurations like pipeline variables, stages... And it also includes all specific configuration for subprojects.

It defines when the pipeline should run, and in which environment it runs.

Specific project CI

In these GitLab files we can find templates and specific jobs to build and test the applications.

Pipelines

Pipeline example

Stages

Pipeline stages are defined in the main CI file. Each job can be linked to a stage using the stage: keyword (stages can be test, build, deploy, ...)

DAG pipelines

Usually, GitLab pipelines move on to the next stage once the current stage in completed (these are the "basic pipelines").

However in GitLab DAG (directed acyclic graph) pipelines, it is not needed to wait for the completion of each stage to move on. Jobs can run whatever the stage status. Instead, jobs depend on other jobs thanks to using the keyword needs:. Kamea uses DAG pipelines.

GitLab's general pipeline documentation

GitLab's DAG pipeline documentation

Variables and secrets

Secrets and other pipeline variables are stored in the GitLab CI/CD Variables (available in the project's CI/CD settings). They can be shared across all environments, or separated for one environment.

Predefined GitLab CI values are listed in these docs.

Deployment

Deployment jobs

Environments

Environments help to keep track of which code is deployed, and where.

This project has two environments by default: dev and prod.

  • dev environment is used for development purposes.

  • prod is the production environment.

    It corresponds to the latest tag starting with prod-.

Each environment is made of sub-environments. For example infrastructure, management-front-end, management-api are services that can exist in each of the environments. Therefore, the dev environment exists as dev/infrastructure, dev/management-front-end and so on.

Each of the three environments can deploy to its own Azure resource group as needed. You can set the project's CI/CD variables by scoping variables to an environment:

  • AZURE_RESOURCE_GROUP determines which resource group the deployment should go to
  • PROJECT_NAME is used as prefix in the deployed Azure resources, and as name of the corresponding Terraform state stored in GitLab.

You can see how PROJECT_NAME is scoped to each environment in the Variables settings:

Scoped variables in the Variables settings

Deployment

Deploying a development version

The latest changes on main are automatically deployed to the dev environment.

Other branches do not deploy on dev. However the init, test and build stages still have access to the dev environment. This is useful for terraform:plan for example.

Deploying a production

To deploy a production release:

  1. Make sure the version you want to release completes successfully on a lower level deployment. This minimizes risks of failing release deployments.
  2. Tag your commit with prod-X.Y.Z, X.Y.Z being your version.
  3. Push the tag on the remote.
  4. You can watch the pipeline progress on the CI/CD > Pipelines overview.

Deployments on environments

You can see the overview of deployments on your environments in Deployments > Environments.

All CI environments

You can find the exact commits that correspond to your deployment in the environment "Show all" details:

Example production environment

Terraform

All terraform states are stored directly on GitLab. They are available in the project's Infrastructure > Terraform settings.

A new state is created simply by referencing one with a new name. In Kamea, the Terraform state has the project name, so a new project name will create a new Terraform state.