debian-mirror-gitlab/doc/ci/quick_start/README.md

236 lines
8.5 KiB
Markdown
Raw Normal View History

2019-09-04 21:01:54 +05:30
---
type: reference
---
2018-03-17 18:26:18 +05:30
# Getting started with GitLab CI/CD
2015-09-25 12:07:36 +05:30
2019-09-04 21:01:54 +05:30
NOTE: **Note:**
2020-03-09 13:42:32 +05:30
Starting from version 8.0, GitLab [Continuous Integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) (CI)
2016-06-02 11:05:42 +05:30
is fully integrated into GitLab itself and is [enabled] by default on all
projects.
2015-09-25 12:07:36 +05:30
2019-09-04 21:01:54 +05:30
NOTE: **Note:**
Please keep in mind that only project Maintainers and Admin users have
the permissions to access a project's settings.
2019-10-12 21:52:04 +05:30
NOTE: **Note:**
Coming over to GitLab from Jenkins? Check out our [reference](../jenkins/index.md)
for converting your pre-existing pipelines over to our format.
2020-03-09 13:42:32 +05:30
GitLab offers a [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) service. For each commit or push to trigger your CI
[pipeline](../pipelines.md), you must:
2016-06-02 11:05:42 +05:30
2020-03-09 13:42:32 +05:30
- Add a [`.gitlab-ci.yml` file](#creating-a-gitlab-ciyml-file) to your repository's root directory.
- Ensure your project is configured to use a [Runner](#configuring-a-runner).
2016-06-02 11:05:42 +05:30
2020-03-09 13:42:32 +05:30
The `.gitlab-ci.yml` file tells the GitLab Runner what to do. A simple pipeline commonly has
three [stages](../yaml/README.md#stages):
2016-06-02 11:05:42 +05:30
2020-03-09 13:42:32 +05:30
- `build`
- `test`
- `deploy`
2015-09-25 12:07:36 +05:30
2020-03-09 13:42:32 +05:30
You do not need to use all three stages; stages with no jobs are ignored.
2016-08-24 12:49:21 +05:30
2020-03-09 13:42:32 +05:30
The pipeline appears under the project's **CI/CD > Pipelines** page. If everything runs OK (no non-zero
return values), you get a green check mark associated with the commit. This makes it easy to see
whether a commit caused any of the tests to fail before you even look at the job (test) log. Many projects use
GitLab's CI service to run the test suite, so developers get immediate feedback if they broke
something.
2015-09-25 12:07:36 +05:30
2020-03-09 13:42:32 +05:30
It's also common to use pipelines to automatically deploy
tested code to staging and production environments.
2015-09-25 12:07:36 +05:30
2016-06-02 11:05:42 +05:30
---
2019-09-04 21:01:54 +05:30
This guide assumes that you have:
2016-06-02 11:05:42 +05:30
2019-12-26 22:10:19 +05:30
- A working GitLab instance of version 8.0+ or are using
2019-09-04 21:01:54 +05:30
[GitLab.com](https://gitlab.com).
- A project in GitLab that you would like to use CI for.
- Maintainer or owner access to the project
2016-06-02 11:05:42 +05:30
Let's break it down to pieces and work on solving the GitLab CI puzzle.
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
## Creating a `.gitlab-ci.yml` file
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
Before you create `.gitlab-ci.yml` let's first explain in brief what this is
all about.
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
### What is `.gitlab-ci.yml`
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
The `.gitlab-ci.yml` file is where you configure what CI does with your project.
It lives in the root of your repository.
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
On any push to your repository, GitLab will look for the `.gitlab-ci.yml`
2017-08-17 22:00:37 +05:30
file and start jobs on _Runners_ according to the contents of the file,
2015-12-23 02:04:40 +05:30
for that commit.
2015-09-25 12:07:36 +05:30
2016-08-24 12:49:21 +05:30
Because `.gitlab-ci.yml` is in the repository and is version controlled, old
versions still build successfully, forks can easily make use of CI, branches can
have different pipelines and jobs, 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][blog-ci].
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
### Creating a simple `.gitlab-ci.yml` file
2017-08-17 22:00:37 +05:30
>**Note:**
`.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file
so you have to pay extra attention to indentation. Always use spaces, not tabs.
2015-12-23 02:04:40 +05:30
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.
2015-09-25 12:07:36 +05:30
```yaml
2019-09-04 21:01:54 +05:30
image: "ruby:2.5"
2015-09-25 12:07:36 +05:30
before_script:
2015-12-23 02:04:40 +05:30
- apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
- ruby -v
- which ruby
2019-02-15 15:39:39 +05:30
- gem install bundler --no-document
2015-12-23 02:04:40 +05:30
- bundle install --jobs $(nproc) "${FLAGS[@]}"
2015-09-25 12:07:36 +05:30
rspec:
script:
- bundle exec rspec
rubocop:
script:
- bundle exec rubocop
```
2017-08-17 22:00:37 +05:30
This is the simplest possible configuration that will work for most Ruby
2015-12-23 02:04:40 +05:30
applications:
1. Define two jobs `rspec` and `rubocop` (the names are arbitrary) with
different commands to be executed.
1. Before every job, the commands defined by `before_script` are executed.
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
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 (in
our case `rspec` and `rubocop`) and always have to contain the `script` keyword.
2017-08-17 22:00:37 +05:30
Jobs are used to create jobs, which are then picked by
2015-12-23 02:04:40 +05:30
[Runners](../runners/README.md) and executed within the environment of the Runner.
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
What is important is that each job is run independently from each other.
2015-09-25 12:07:36 +05:30
2018-05-09 12:01:36 +05:30
If you want to check whether the `.gitlab-ci.yml` of your project is valid, there is a
2019-07-07 11:18:12 +05:30
Lint tool under the page `/-/ci/lint` of your project namespace. You can also find
2018-03-17 18:26:18 +05:30
a "CI Lint" button to go to this page under **CI/CD ➔ Pipelines** and
2017-08-17 22:00:37 +05:30
**Pipelines ➔ Jobs** in your project.
2015-09-25 12:07:36 +05:30
2016-08-24 12:49:21 +05:30
For more information and a complete `.gitlab-ci.yml` syntax, please read
2019-12-21 20:55:43 +05:30
[the reference documentation on `.gitlab-ci.yml`](../yaml/README.md).
2015-12-23 02:04:40 +05:30
### Push `.gitlab-ci.yml` to GitLab
2017-08-17 22:00:37 +05:30
Once you've created `.gitlab-ci.yml`, you should add it to your Git repository
2015-12-23 02:04:40 +05:30
and push it to GitLab.
2015-09-25 12:07:36 +05:30
2020-03-09 13:42:32 +05:30
```shell
2015-09-25 12:07:36 +05:30
git add .gitlab-ci.yml
2015-12-23 02:04:40 +05:30
git commit -m "Add .gitlab-ci.yml"
2015-09-25 12:07:36 +05:30
git push origin master
```
2016-08-24 12:49:21 +05:30
Now if you go to the **Pipelines** page you will see that the pipeline is
pending.
2015-12-23 02:04:40 +05:30
2018-05-09 12:01:36 +05:30
NOTE: **Note:**
2019-12-26 22:10:19 +05:30
If you have a [mirrored repository where GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter),
2018-05-09 12:01:36 +05:30
you may need to enable pipeline triggering in your project's
**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.
2017-08-17 22:00:37 +05:30
You can also go to the **Commits** page and notice the little pause icon next
2015-12-23 02:04:40 +05:30
to the commit SHA.
![New commit pending](img/new_commit.png)
2017-08-17 22:00:37 +05:30
Clicking on it you will be directed to the jobs page for that specific commit.
2015-12-23 02:04:40 +05:30
2017-08-17 22:00:37 +05:30
![Single commit jobs page](img/single_commit_status_pending.png)
2015-12-23 02:04:40 +05:30
2018-03-17 18:26:18 +05:30
Notice that there is a pending job which is named after what we wrote in
`.gitlab-ci.yml`. "stuck" indicates that there is no Runner configured
yet for this job.
2015-12-23 02:04:40 +05:30
2017-08-17 22:00:37 +05:30
The next step is to configure a Runner so that it picks the pending jobs.
2015-12-23 02:04:40 +05:30
## Configuring a Runner
2017-08-17 22:00:37 +05:30
In GitLab, Runners run the jobs that you define in `.gitlab-ci.yml`. A Runner
2016-08-24 12:49:21 +05:30
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,
2018-11-08 19:23:39 +05:30
so the only requirement is that the Runner's machine has network access to the
GitLab server.
2015-12-23 02:04:40 +05:30
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](../runners/README.md) documentation.
You can find whether any Runners are assigned to your project by going to
2018-03-17 18:26:18 +05:30
**Settings ➔ CI/CD**. Setting up a Runner is easy and straightforward. The
2017-08-17 22:00:37 +05:30
official Runner supported by GitLab is written in Go and its documentation
can be found at <https://docs.gitlab.com/runner/>.
2015-12-23 02:04:40 +05:30
In order to have a functional Runner you need to follow two steps:
1. [Install it][runner-install]
2019-02-15 15:39:39 +05:30
1. [Configure it](../runners/README.md#registering-a-specific-runner)
2015-12-23 02:04:40 +05:30
Follow the links above to set up your own Runner or use a Shared Runner as
described in the next section.
Once the Runner has been set up, you should see it on the Runners page of your
2018-03-17 18:26:18 +05:30
project, following **Settings ➔ CI/CD**.
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
![Activated runners](img/runners_activated.png)
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
### Shared Runners
2015-09-25 12:07:36 +05:30
2017-08-17 22:00:37 +05:30
If you use [GitLab.com](https://gitlab.com/) you can use the **Shared Runners**
2015-12-23 02:04:40 +05:30
provided by GitLab Inc.
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
These are special virtual machines that run on GitLab's infrastructure and can
build any project.
2015-09-25 12:07:36 +05:30
2017-08-17 22:00:37 +05:30
To enable the **Shared Runners** you have to go to your project's
2018-03-17 18:26:18 +05:30
**Settings ➔ CI/CD** and click **Enable shared runners**.
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
[Read more on Shared Runners](../runners/README.md).
2015-09-25 12:07:36 +05:30
2017-08-17 22:00:37 +05:30
## Seeing the status of your pipeline and jobs
2015-09-25 12:07:36 +05:30
2016-04-02 18:10:28 +05:30
After configuring the Runner successfully, you should see the status of your
2015-12-23 02:04:40 +05:30
last commit change from _pending_ to either _running_, _success_ or _failed_.
2015-09-25 12:07:36 +05:30
2016-08-24 12:49:21 +05:30
You can view all pipelines by going to the **Pipelines** page in your project.
![Commit status](img/pipelines_status.png)
2017-08-17 22:00:37 +05:30
Or you can view all jobs, by going to the **Pipelines ➔ Jobs** page.
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
![Commit status](img/builds_status.png)
2015-09-25 12:07:36 +05:30
2017-08-17 22:00:37 +05:30
By clicking on a job's status, you will be able to see the log of that job.
This is important to diagnose why a job failed or acted differently than
2015-12-23 02:04:40 +05:30
you expected.
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
![Build log](img/build_log.png)
2015-09-25 12:07:36 +05:30
2015-12-23 02:04:40 +05:30
You are also able to view the status of any commit in the various pages in
2017-08-17 22:00:37 +05:30
GitLab, such as **Commits** and **Merge requests**.
2016-04-02 18:10:28 +05:30
2016-06-02 11:05:42 +05:30
## Examples
2015-09-25 12:07:36 +05:30
2016-06-02 11:05:42 +05:30
Visit the [examples README][examples] to see a list of examples using GitLab
CI with various languages.
2015-09-25 12:07:36 +05:30
2017-08-17 22:00:37 +05:30
[runner-install]: https://docs.gitlab.com/runner/install/
2019-12-21 20:55:43 +05:30
[blog-ci]: https://about.gitlab.com/blog/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/
2016-06-02 11:05:42 +05:30
[examples]: ../examples/README.md
[enabled]: ../enable_or_disable_ci.md