Quickstart for GitLab Continuous Integration

Within a project, various components such as your codebase, CI configuration, planning, analytics, and team members are managed. In this guide, we will create a new project with a blank slate, containing only a readme file.

• Create a new project by clicking the plus icon at the right side of the top bar, and selecting New project/repository
• Select Create Blank project. Under Project name type my-project.
• Click Create project.
• Congratulations! you have successfully created your first project.

In GitLab, the CI configuration is defined in code using YAML syntax. This configuration specifies instructions to the runner machine regarding job execution, job order, job conditions, and more. To define the CI configuration, you need to create a file called .gitlab-ci.yml, which should be located at the root of your repository. In this guide, we will utilize the Web IDE to create and edit this file.

To access the Web IDE, simply click on the Web IDE quick button located in your project. Once inside the Web IDE, navigate to the file explorer on the left side. Right-click within the file explorer and choose the New File option. Name the newly created file .gitlab-ci.yml.

The order of job executions is determined by the stages defined in the configuration. In this guide, we will define three stages: build, test, and package, in that specific order. Copy and paste the following code into the .gitlab-ci.yml file:

  stages:
    - build
    - test
    - package

Envision a scenario where you are tasked with creating two text files. It is of utmost importance that the concatenation of these files includes the phrase "Hello world." Our objective is to build, test, and package this requirement utilizing pipeline jobs.

We will specify a build job that accomplishes the following tasks: creating a text file with the word "Hello," creating another text file with the word "World," and generating a third file that stores the combined content of the two files. We will save the third file as an artifact, so subsequent jobs in test and package stages will be able to access it. Please insert the provided code below the stages block:

  build-job:
    stage: build
    script:
      - echo "Hello " | tr -d "\n" > file1.txt
      - echo "world" > file2.txt
      - cat file1.txt file2.txt > compiled.txt
    artifacts:
    paths:
      - compiled.txt

To validate the integrity of our build, we will incorporate a test job. This job will examine whether the compiled.txt file indeed contains the expected phrase "Hello world". Please insert the following code below the build job:

  test:
    stage: test
    script: cat compiled.txt | grep -q 'Hello world '

Upon successful completion of the test, our next objective is to generate a package for our code. To accomplish this, we will include a package job. It is important to note that if the test fails, the entire pipeline will be deemed unsuccessful and will not proceed. Please insert the provided code below the test job:

  package:
    stage: package
    script: cat compiled.txt | gzip > packaged.gz
    artifacts:
      paths:
        - packaged.gz

  stages:          # List of stages for jobs, and their order of execution
    - build
    - test
    - package

  build-job:
    stage: build
    script:
      - echo "Hello " | tr -d "\n" > file1.txt
      - echo "world" > file2.txt
      - cat file1.txt file2.txt > compiled.txt
    artifacts:
      paths:
        - compiled.txt

  test:
    stage: test
    script: cat compiled.txt | grep -q 'Hello world'

  package:
    stage: package
    script: cat compiled.txt | gzip > packaged.gz
    artifacts:
      paths:
        - packaged.gz

Here is a link to the configuration file in our example project.

Congratulations!! you built your first CI pipeline.

To activate continuous integration (CI) within our project, we must push the .gitlab-ci.yml file to the repository. Once this file is located at the root of the repository, each commit made to the project will automatically initiate a CI pipeline. The initial pipeline will commence immediately after pushing this file to the server.

• Click on the Merge icon located to the left of the file explorer.
• Provide a commit message such as "Adding CI configuration."
• Click on Commit & Push.
• When prompted with "Commit to a new branch?" select "No, Use the current branch main".
• To return to your project, click the Go to project button situated on the bottom left side.

Congratulations! Your project is now successfully configured to automatically initiate a CI pipeline for every code commit.

While the pipeline is running, you can monitor the status of it in the CI/CD tab. This feature allows you to easily track the progress of your jobs, including their execution status (such as whether they have started, passed, failed, etc), as well as any output generated by your job scripts.

• Navigate to the GitLab project and locate the left menu.
• Click on CI/CD in the menu, click Pipelines.
• On the Pipelines page, locate the pipeline button in the Status column. Click on it to open the pipeline graph.
• Now, you can observe the jobs and their respective statuses within the pipeline graph.
• To explore a specific job, click on it to open the job console. This console displays all the steps executed on the Runner machine.
• Open the package job console to view the steps that were processed by the runner.
• The package job generates an artifact, you can download it by clicking the download button located on the right side.
• By following these steps, you can effectively track the pipeline status, inspect job details, and retrieve any relevant artifacts or packages produced during the pipeline execution.

Congratulations on successfully running your first pipeline. The pipeline succeeded! You have now viewed the results and downloaded the job artifact.

We will change the expected value in the test job, the test job will fail as well as the entire pipeline will fail.

• Edit the test job by modifying the phrase "Hello World" to "hello world" (with lowercase letters).
• Commit the code changes and proceed to view the pipeline, similar to Step 4.
• Upon inspecting the pipeline, you will observe that the test job has failed. Additionally, the subsequent package job did not start, and the pipeline itself failed as expected.

In step 5 we saw that job failure failed the entire pipeline. You can introduce logic into your pipeline that determines when a job failure will cause the entire pipeline to fail with the following steps:

• Assess the conditions under which you want a job failure to result in pipeline failure. For example, you may want to enforce pipeline failure if a job fails on the main or default branch, while allowing job failures on other branches to proceed with the pipeline.
• Define rules that govern the failure behavior. You can leverage variables such as $CI_COMMIT_BRANCH to check the current branch and make decisions based on it.
• Set the appropriate conditions and specify whether the job should be marked as allow_failure: false or allow_failure: true.

• Add rules/if conditions to your test job.
• Use the allow_failure keyword set to true or false based on the branch.

  test:
    stage: test
    script: cat compiled.txt | grep -q 'Hello world'
    rules:
      - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
        allow_failure: false
      - if: $CI_COMMIT_BRANCH
        allow_failure: true

To streamline the pipeline configuration setup, you can leverage the built-in pipeline templates provided by GitLab. These templates offer pre-defined configurations for common use cases, such as security scans, aws deployments, etc.

Follow these steps to utilize the built-in pipeline templates:

• Explore the available pipeline templates offered by GitLab for various scenarios such as building, testing, deploying, and more. These templates can be found here.
• Select the template that aligns with your requirements.
• Incorporate the template into your pipeline configuration by referencing it in your .gitlab-ci.yml file. You can typically do this by importing the template using the include keyword and specifying the path or URL to the template file.

In this guide we will add Code Quality scan to our configuration using the Code-Quality template.

Include the code quality template to your .gitlab-ci.yml by adding this code below the stages block.

  include:
    - template: Jobs/Code-Quality.gitlab-ci.yml

Commit and push this change.

You will notice that a Code quality job was added to your pipeline. The Code Quality scanner will thoroughly analyze any code changes committed to this repository, and provide valuable feedback, highlighting any code quality issues that require attention and improvement. This valuable insight allows you to enhance the overall quality of your codebase and optimize its performance.

That's it! With these steps, you should be able to get started with GitLab CI and automate your project's build and testing processes.