⬅ Back to Catalogue

Introduction#

This page focuses on interpretation to help you make sense of GitLab CI in the context of your coursework and not so much on creating your own CI jobs. If you want to dive deeper, you can read another detailed tutorial to learn how to use CI/CD pipelines to automatically build, test, deploy your code and many more useful techniques, including but not limited to repository grouping, access control and secret management.

What is GitLab CI?#

GitLab CI (Continuous Integration) is a feature of GitLab where you can run and test software in a repository on the GitLab server every time you push a new commit. The idea is that the instructions for testing the software in your repository are contained as a command line script in a special file. Whenever you push commits to GitLab, the GitLab server runs these testing commands and gives you feedback on whether your software is working.

CI stands for Continuous Integration. It’s a software engineering methodology that encourages regular testing of a whole software product. This might involve a complex build process in a big project and would contrast with testing specific modules (e.g., unit testing). In our case, the important bit is the practice of running automated tests after each commit.

Why is GitLab CI important in courses at ANU#

Some computing courses at ANU use GitLab CI to help test code you have written in labs or assignments. The outcomes of these tests can be useful as feedback to you (as a student) to know whether you have completed parts of an assignment specification. Your tutors might use CI tests to verify you’ve completed a lab or assignment. Some CI jobs actually create an artefact (a file) that might be used in marking an assignment (e.g., a PDF file showing which tests your code has passed).

This varies by course, but in general it’s important to understand the feedback that GitLab CI is providing to you and how to interpret it.

The kinds of things that CI can check#

GitLab CI can do a lot of different things (if you can write a shell script to do it, CI can do it).

GitLab CI is often used to:

  • check you that required assignment files are present and “filled in” in some way
  • check that the wordcount of a file is within the limit
  • check that your code “compiles”
  • deploy your completed project to a website (so you can test it out and share with others)
  • run tests of different features in your code
  • create a PDF from text files in your for viewing and marking

Different courses use GitLab CI in different ways so you would have to check individual assignment specifications to see if and how it is used.

What are CI jobs?#

CI jobs (Continuous Integration jobs) are individual tasks or steps that are parts of an automated process to test and build code. They run every time a developer pushes code to a shared repository (like GitLab) to make sure everything works properly.

The life cycle of a CI job#

The life cycle of a CI job refers to the series of steps or stages that a job goes through from start to finish in the Continuous Integration (CI) process. Here’s a simplified breakdown:

  1. Triggered. The CI job starts when someone makes a change to the codebase, like pushing new code or opening a merge request. This triggers the CI system to begin running the job automatically. Example: You push a new feature to GitHub, and the CI job starts.

  2. Queued. Before the CI job can run, it may be placed in a queue if the system is busy running other jobs. Once it’s ready, it will start.

  3. Executed. The CI job is now running, and it performs the tasks designed for it, which may include:

    • Installing dependencies: It sets up everything needed to run the code (like libraries or tools).
    • Running tests: The job runs automated tests to check if the new code works as expected.
    • Building the code: If required, the job compiles the code to make sure it can be turned into a working app.

  4. Success or Failure. Once the job finishes its tasks, it reports the result:

    • Success: If everything went smoothly (tests passed, code built properly), the job is marked as successful.
    • Failure: If something went wrong (like a test failed or the code didn’t build), the job is marked as failed.

  5. Notifications. The results of the CI job are usually sent to the developers or displayed in the system:

    • If successful, you might get a green checkmark in your merge request or repository.
    • If failed, you’ll get a red mark and details on what went wrong so you can fix it.

How does the .gitlab-ci.yml file work?#

The .gitlab-ci.yml file is like a recipe that tells GitLab how to run CI and CD jobs in different stages. GitLab reads this file and follows the instructions to run the jobs whenever you push code to the repository. There are a few concepts you need to know about how it works:

  • Define Jobs: In the .gitlab-ci.yml file, you define jobs, which are specific tasks that GitLab should do, such as running tests, building the app, or deploying it to a server. Here’s a simple example of a job:
test:
  script:
    - npm install
    - npm test

This job runs two commands: installing the necessary packages (npm install) and running the tests (npm test).

  • Stages: You can organize jobs into stages to control the order in which they run. For example, you may have a “compile” stage that runs first, and a “test” stage that runs after compiling is successful:
stages:
  - compile
  - test
  • Runners: The jobs are executed by runners, which are servers that GitLab uses to run the tasks specified in the .gitlab-ci.yml file. You don’t have to manage this because GitLab takes care of them.
  • Artifacts: You can tell GitLab to save files or results (like build outputs or test results) as artifacts that you can review later. This feature is always used for saving the test results of your assignments. A simple example is like below:
artifacts:
  paths:
    - build/

Making sense of the CI status#

The CI status is a simple indicator that tells you whether your code is working correctly in the automated CI process. It’s an easy way to check if your code changes are good to go or if there’s something wrong that needs to be fixed.

There are six CI statuses: Success, Failure, Pending, Running, Skipped and Canceled. For each one of them, you should see a different indicator:

  • For success, you should see a green checkmark or “Passed”, meaning all the CI jobs (tests, builds, etc.) ran successfully without any issues.
  • For failure, you should see a red X or “Failed”, meaning one or more CI jobs failed. This could be due to a test that didn’t pass, a build error, or some other problems.
  • For pending, you should see clock icon or “Pending”, meaning The CI jobs are waiting in line to run.
  • For running, you should see a circle or “Running”, meaning the CI jobs are currently being executed.
  • For skipped, you should see a gray Icon or “Skipped”.
  • For canceled, you should see an orange icon or “Canceled”.

Reading job logs#

Job logs are detailed reports that show everything a CI job did when it ran. They help you understand what happened during the job, especially if something went wrong.

You can read different parts of a job log from top to bottom:

  • At the top of the log, you’ll usually see the setup information, like what environment or runner the job is using (e.g., Linux, Docker, etc.).
  • Following that, the log shows each command the CI job ran. For example, if the job is supposed to install dependencies, you’ll see commands like pip install and the output of it.
  • Lastly, a success or error message should be presented. For example, after running tests, it may show something like All tests passed or IndexError: list index out of range.

One knack to read the log is to look for words like “error” “failed” or “warning” in the log. These highlight where the job had issues. You can also pay attention to the exit code because “0” usually means success while other numbers indicates a failure.

Downloading artefacts#

Artifacts in a CI pipeline are files or outputs that are generated by a CI job and saved for later use. These could include things like build files, test results, or logs. For example, in ANU GitLab, tutors and conveners can download the artifacts directly from the job’s page. By doing that, they can get a .zip file containing your assignment’s test results, to open and review locally.

Frequently Asked Questions#

What’s continuous integration?#

Continuous Integration (CI) is just a fancy name for a bunch of commands which are executed on the GitLab server every time you successfully push a new commit to your repository. This can be used to do all sorts of things, for example to check that you haven’t forgotten to commit a file (e.g. references.md). These commands are called “CI jobs”.

Why am I getting “Pipeline #xxxx has failed…” emails from GitLab?#

This means that:

  1. You are taking a course that uses GitLab CI.
  2. You have committed code to an assignment or lab repository.
  3. A GitLab CI job has run but not been 100% successful (it may have been partially successful).

It doesn’t necessary mean you have done anything wrong, but you should check the job trace to see what is happening and check your assignment/lab specification to see what you should expect.

This isn’t a guarantee of the “correctness” of your submission (it doesn’t actually run your code), it’s a just a checklist of the very basic things your code must do (like compile successfully).

So if all the CI tests pass, do I get 100% for the assignment?#

No. It just checks the “bare minimum”, that your assignment is valid and the most important components are in place.

Should I be worried if my submission fails the CI checks?#

Not initially. What you need to do is have a look at what has failed and make sure that you’re working towards fixing them up. As the submission deadline approaches and you finish off your assignment you should see fewer and fewer failures.

How long does my CI job take to run?#

Most CI jobs take less than one minute to run. However, if there may be a lot of students pushing code to gitlab, and we’ve only got a limited number of servers to run the CI jobs on, so it’s quite likely that your job won’t start straight away if the servers are already busy.

Your CI job goes into a queue and will run as soon as possible. So if a lot of people are pushing (e.g. if it’s close to the deadline) then you might have to be a bit patient.

If the CI job takes ages to run, does that mean my code hasn’t been accepted before the deadline?#

No. The CI checks are just there to provide helpful feedback to you—they have no impact on whether your code is submitted (or the time of submission). The submission time is based only on the timestamp when GitLab receives your push.

Can I see whether my submission passes the CI checks through the GitLab web interface?#

Yes. Go to the web interface for your repo, and click on “CI / CD” in the sidebar. You’ll see a view which gives you info about the last CI run (which should have happened last time you pushed).

I’m sick of getting these CI emails, can I disable them?#

Yes. If you want to disable this email notification, go to your account setting in GitLab (click on your profile picture, then select Notifications). Change the notification level of your assignment repo to “Custom”, then in the pop-up window de-select “Failed pipeline”.

Can I modify the .gitlab-ci.yml file?#

Usually this isn’t a good idea unless your course convenor specifically allows you to do so.

Moving On#

This page briefly explains the key concepts of GitLab CI and some commonly asked questions. You should now be able to broadly understand the answer to questions like what GitLab CI is, what a CI job is and how to read a job log. Remember, don’t change the .gitlab-ci.yml file unless your course convenor specifically allows you to do so.

Next, we have a cheatsheet to summarise the commonly used commands of Linux and Git and some key points of good practices. Think of it as your go—to guide when you need a reminder of how to perform a task in Git, without having to dive deep into the documentation.

13
bars search caret-down plus minus arrow-right times