gitlab-org--gitlab-foss/doc/ci/quick_start

Quick Start

GitLab Continuous Integration (CI) is fully integrated into GitLab itself. You only need to enable it in the Services settings of your project.

This guide assumes that you:

• have a working GitLab instance of version 8.0 or higher or are using GitLab.com
• have a project in GitLab that you would like to use CI for

In brief, the steps needed to have a working CI can be summed up to:

1. Create a new project
2. Add .gitlab-ci.yml to the git repository and push to GitLab
3. Configure a Runner

From there on, on every push to your git repository the build will be automagically started by the runner and will appear under the project's /builds page.

Now, let's break it down to pieces and work on solving the GitLab CI puzzle.

1. Enable GitLab CI

After creating a new project, the first thing to do is enable the GitLab CI service in your project's settings if it isn't already enabled.

Read how to enable the GitLab CI service.

1. Creating a .gitlab-ci.yml file

GitLab CI service is enabled automatically on the first push of a .gitlab-ci.yml file in your repository and this is the recommended way.

For other methods read how to enable the GitLab CI service.

What is .gitlab-ci.yml

The .gitlab-ci.yml file is where you configure what CI does with your project. It lives in the root of your repository.

On any push to your repository, GitLab will look for the .gitlab-ci.yml file and start builds on Runners according to the contents of the file, for that commit.

Because .gitlab-ci.yml is in the repository, it is version controlled, old versions still build succesfully, forks can easily make use of CI, branches can have separate builds and you have a single source of truth for CI. You can read more about the reasons why we are using .gitlab-ci.yml in our blog about it.

.gitlab-ci.yml is a YAML file.

Creating a simple .gitlab-ci.yml file

You need to create a file named .gitlab-ci.yml in the root directory of your repository. Below is an example for a Ruby on Rails project.

before_script:
  - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
  - ruby -v
  - which ruby
  - gem install bundler --no-ri --no-rdoc
  - bundle install --jobs $(nproc)  "${FLAGS[@]}"

rspec:
  script:
    - bundle exec rspec

rubocop:
  script:
    - bundle exec rubocop

This is the simplest possible build configuration that will work for most Ruby applications:

1. Define two jobs rspec and rubocop with different commands to be executed.
2. Before every job, the commands defined by before_script are executed.

The .gitlab-ci.yml file defines sets of jobs with constraints of how and when they should be run. The jobs are defined as top-level elements with a name and always have to contain the script name. Jobs are used to create builds, which are then picked by Runners and executed within the environment of the Runner.

What is important is that each job is run independently from each other.

If you want to check whether your .gitlab-ci.yml file is valid, there is a Lint tool under the page /ci/lint of your GitLab instance. You can also find the link under Settings -> CI settings in your project.

For more information and a complete .gitlab-ci.yml syntax, please check the documentation on .gitlab-ci.yml.

Push .gitlab-ci.yml to GitLab

Once you've created .gitlab-ci.yml, you should add it to your git repository and push it to GitLab.

git add .gitlab-ci.yml
git commit -m "Add .gitlab-ci.yml"
git push origin master

Now if you go to the Builds page you will see that the builds are pending.

You can also go to the Commits page and notice the little clock icon next to the commit SHA.

Clicking on the clock icon you will be directed to the builds page for that specific commit.

Notice that there are two jobs pending which are named after what we wrote in .gitlab-ci.yml. The red triangle indicates that there is no Runner configured yet for these builds.

The next step is to configure a Runner so that it picks the pending jobs.

2. Configuring a Runner

In GitLab, Runners run the builds that you define in .gitlab-ci.yml. A Runner can be a virtual machine, a VPS, a bare-metal machine, a docker container or even a cluster of containers. GitLab and the Runners communicate through an API, so the only needed requirement is that the machine on which the Runner is configured to have Internet access.

A Runner can be specific to a certain project or serve multiple projects in GitLab. If it serves all projects it's called a Shared Runner.

Find more information about different Runners in the Runners documentation.

You can find whether any Runners are assigned to your project by going to Settings -> Runners.

Setting up a Runner is easy and straightforward. The official Runner supported by GitLab is written in Go and can be found at https://gitlab.com/gitlab-org/gitlab-ci-multi-runner.

In order to have a functional Runner you need to:

1. Install it
2. Configure it

For other types of unofficial Runners written in other languages, see the instructions for the various GitLab Runners.

Once the Runner has been set up, you should see it on the Runners page of your project, following Settings -> Runners.

Shared Runners

If you use GitLab.com you can use Shared Runners provided by GitLab Inc.

These are special virtual machines that are run on GitLab's infrastructure that can build any project.

To enable Shared Runners you have to go to your project's Settings -> Runners and click Enable shared runners.

Read more on Shared Runners.

3. Seeing the status of your build

After configuring the Runner succesfully, you should see the status of your last commit change from pending to either running, success or failed.

You can view all builds, by going to the Builds page in your project.

By clicking on a Build ID, you will be able to see the log of that build. This is important to diagnose why a build failed or acted differently than you expected.

You are also able to view the status of any commit in the various pages in GitLab, such as Commits and Merge Requests.

Next steps

Awesome! You started using CI in GitLab!

Next you can look into doing more with the CI. Many people are using GitLab to package, containerize, test and deploy software.

We have a number of examples available.