programming-basics-materials/gitlab-cicd.md

marp	paginate	math	theme	title
true	true	mathjax	buutti	GitLab CI/CD

GitLab CI/CD

Jobs

• Jobs are the individual units of work that form your CI/CD pipeline. The jobs can be anything, but usually relate to building, testing and packaging the product.
• The common thing between all jobs is that they can either fail or pass. Every executable script in all operating systems return an exit code of either
  • 0 which indicates success, or
  • 1 - 255 which indicate error.
• The exit code returned from an executed job determines whether the job passes (exit code 0) or fails (exit code 1-255).
  • Failing tests typically return an exit code of 1

Runners

• GitLab Runners are applications that run the jobs in your pipeline.
  • GitLab Runners can be installed to your own system and registered to be used by anyone or your group.
• If you use GitLab.com, your projects use shared runners by default.
  • This is the most convenient way to run the jobs.
• Note: To use GitLab Runners, you need to give your credit/debit card info to GitLab. You won't be charged any fees, however.

.gitlab-ci.yml

• The entire GitLab CI/CD pipeline is controlled with a single YAML file called .gitlab-ci.yml.
  • Notice that the file name starts with a dot, and is in all lowercase!
  • VSC recognizes the file name and marks it with a GitLab icon.
• Individual jobs such as build, test and deploy are set up by defining them in the file
• Keyword reference: https://docs.gitlab.com/ee/ci/yaml/

# very simple .gitlab-ci.yml

test-job:
  stage: test
  script:
    - echo "Hello Pipeline!"

A minimal pipeline

• We will start by creating a minimal project with a pipeline.
• The project itself will contain only a README.md file and a pipeline configuration .gitlab-ci.yml file.
• We will use this project to run our first pipelines.

Create a project

1. Start by creating a new project New Project > Create blank project then after filling the necessary fields, Create Project
2. Clone the project locally, and open the project folder in VSC.

Add a .gitlab-ci.yml file

3. Add a .gitlab-ci.yml file to your project.
   • We are creating a barebones project, so we'll include only one job, executed in the test stage.
   • The only thing the job does is print a message to the pipeline log.
   • We will add more complex configurations soon.
4. When the file is created, add, commit and push your changes to the repository.
   • GitLab will automatically start a new pipeline when it notices that the project has a configuration file.

# .gitlab-ci.yml

test-job:
  stage: test
  script:
    - echo "Hello Pipeline!"

Running the pipeline

• You can observe the pipeline progress from the GitLab project Build > Pipelines

Troubleshooting

• If the job does not succeed, check the log for error messages.
  • Then modify your configuration, commit, and push again.
  • GitLab will run a new pipeline every time a project with a .gitlab-ci.yml file is pushed.
• You can also rerun the pipeline from Build > Pipelines > Run pipeline if the problem was not in the code or your configuration.
  • Examples of cases like this could be errors in the GitLab environment or problems with Azure.

Adding environment variables

• Often our projects use environment variables in the jobs that pipelines run.
• In GitLab the variables used in CI/CD are configured in Settings > CI/CD > Variables

• You can add new variables using the Add variable button, or edit or delete existing variables using the corresponding buttons in the Actions column.

Using Environment Variables

• We can use our environment variables in our configuration files by referring to their names prepended with a $ sign.

# .gitlab-ci.yml

test-job:
stage: test
script:
  - echo "Hello Pipeline v.$VERSION"

Assignment 1: A minimal pipeline

• Following the lecture instructions, create a minimal project with a pipeline configuration that writes a message to the pipeline log.
• The message should include a value that is read from an environment variable.

Pipeline Project

Pipeline linting

• Let's create an actual project with automatic linting.
• We will configure our pipeline to run the linter automatically on every push.
  • This makes sure all code that ends up in our repository follows our syntax standards.

1. Create a new project like you did before. Then, add some code to it.
2. Make sure your project has a linter installed and configured in such a way that the linter can be run from the terminal.
   • In JS/TS project this means package.json file has a script

     "lint": "eslint ."
     

Pipeline dependencies

• GitLab runs the pipelines inside Docker containers. For our linter to work, we need the container to have access to the eslint command.
• This means before we can run the linter, we need to install the required dependencies to our project.
• For this to work, we need to have NPM installed in our container. We need to configure the pipeline to use an image with NPM preinstalled.
• GitLab pulls the images from Docker Hub, so we can choose an appropriate image from there.

3. Configure your YML file like in the example here.

# .gitlab-ci.yml
lint-job:
  image: node:21
  stage: test
  script:
    - npm install
    - npm run lint

Pipeline pass/fail

• Now, if our code has style or syntax problems, the linter will throw an error and the pipeline will fail.
• When all the errors have been fixed, the pipeline passes.

Automated testing

• If our project includes automated testing, we can run tests in a similar fashion.
• They can be run in the same job or a dedicated one.
• Each job uses a different container, so the dependencies need to be installed separately for each container!

  # .gitlab-ci.yml
  lint-job:
  image: node:21
  stage: test
  script:
    - npm install
    - npm run lint
    - npm run test
  

# .gitlab-ci.yml
lint-job:
  image: node:21
  stage: test
  script:
    - npm install
    - npm run lint

test-job:
  image: node:21
  stage: test
  script:
    - npm install
    - npm run test

GitLab cache

• In a Node project the dependencies are stored in the node_modules folder, created only when npm install is run.
• Therefore by default, each stage would be required to download and install the dependencies separately. This is not desirable!
• We define a cache in the .gitlab-ci.yml file, which allows all stages to access the folders defined in the cache parameter.
  • After this we only need to install the dependencies once.

default:
  image: node

cache:
  paths:
    - node_modules/

stages:
  - install
  - lint
  - build
  - deploy

install:
  stage: install
  script:
    - npm install

lint:
  stage: lint
  script:
    - npm run lint

build:
  stage: build
  script:
    - npm run build

deploy:
  stage: deploy
  script:
    - echo "Deploy app here"

Assignment 2: Pipeline Linter

1. Create a new empty repository in GitLab. Clone it to your local machine, and initialize a NPM project into it.
2. Install and configure TypeScript and ESLint. Add some program code (a simple Hello World will do.)
3. Add scripts for starting the program and linting the code. Also include a script to build the code. Make sure everything works locally.

---

4. Add a .gitlab-ci.yml file. It should have four stages:
   • install (where you install the dependencies)
   • lint (where the linter is run)
   • deploy (with a placeholder logging message, we don't actually deploy anything today)
   • It should have an additional build stage as well.
5. Commit and push your changes. Go to GitLab and check that all the jobs run and pass.