Commit 90f4b656 authored by Mike Lewis's avatar Mike Lewis

Merge branch 'docs-ci-getting-started' into 'master'

Docs: Introduction to continuous methods and GitLab CI/CD

Closes #58394

See merge request gitlab-org/gitlab-ce!25611
parents 1b4a20c0 82bd2d47
......@@ -5,10 +5,7 @@ description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Inte
# GitLab Continuous Integration (GitLab CI/CD)
GitLab provides tools for continuously integrating and delivering code.
Within the [entire DevOps lifecycle](../, GitLab CI/CD spans
the [Verify (CI)](../ and [Release (CD)](../ stages.
**GitLab CI/CD** is GitLab's built-in tool for software development using the Continuous Methodology (Continuous Integration, Continuous Delivery, Continuous Deployment).
## Overview
......@@ -16,31 +13,13 @@ CI/CD is a vast area, so GitLab provides documentation for all levels of experti
| Level of expertise | Resource |
| New to the concepts of CI and CD | For a high-level overview, see the [GitLab Continuous Integration & Delivery]( product page. |
| Familiar with the purpose of CI/CD | Delve into GitLab CI/CD by continuing down the page, starting with our [introduction](#introduction). |
| New to the concepts of CI and CD | For a high-level overview, read an [introduction to CI/CD with GitLab](introduction/ |
| Familiar with GitLab CI/CD concepts | After getting familiar with GitLab CI/CD, let us walk you through a simple example in our [quick start guide](quick_start/ |
| A GitLab CI/CD expert | Jump straight to our [`.gitlab.yml`](yaml/ reference. |
## Introduction
The following introduces the process of continuous integration (CI) and continuous delivery (CD):
![Pipeline graph](img/cicd_pipeline_infograph.png)
In this illustration:
- New code is combined with existing code through a commit to a project's [repository](../user/project/repository/
- The newly combined code is sent to a CI [pipeline]( where:
- The code is [built](../user/project/pipelines/
- Unit and integration tests are run over the built code.
- Assuming the build and tests are successful, a CD pipeline is triggered to allow for:
- Review using [Review Apps](review_apps/
- Deploying to configured [environments](
The benefits of CI/CD are vast, allowing automation to be an integral part of your workflow for testing, building, deploying, and monitoring your code.
Because CI and CD with GitLab is broad topic with many possibilities, the rest of this section provides
links to topics and resources needed to make use of GitLab CI/CD.
NOTE: **Note:**
Within the [DevOps lifecycle](../, GitLab CI/CD spans
the [Verify (CI)](../ and [Release (CD)](../ stages.
## Essentials
......@@ -51,6 +30,7 @@ The following documentation provides the minimum required knowledge for making u
| [Getting started with GitLab CI/CD](quick_start/ | Outlines the first steps for configuring GitLab CI/CD. |
| [Introduction to pipelines and jobs]( | Provides an overview of GitLab CI/CD and jobs. |
| [Configuration of your pipelines with `.gitlab-ci.yml`](yaml/ | A comprehensive reference for the `.gitlab-ci.yml` file. |
| [`.gitlab-ci.yml` introduction](../user/project/pages/ | A step-by-step introduction to writing a GitLab CI/CD configuration file (`.gitlab-ci.yml`) for the first time. |
NOTE: **Note:**
Familiarity with [GitLab Runner]( is useful because it is
......@@ -99,7 +79,8 @@ use of advanced features:
### GitLab Pages
GitLab CI/CD can be used to build and host static websites. For more information, see the
documentation on [GitLab Pages](../user/project/pages/
documentation on [GitLab Pages](../user/project/pages/,
or dive right into the [CI/CD step-by-step guide for Pages](../user/project/pages/
## Examples
description: "An overview of Continuous Integration, Continuous Delivery, and Continuous Deployment, as well as an introduction to GitLab CI/CD."
# Introduction to CI/CD with GitLab
In this document we'll present an overview of the concepts of Continuous Integration,
Continuous Delivery, and Continuous Deployment, as well as an introduction to
GitLab CI/CD.
## Introduction to CI/CD methodologies
The continuous methodologies of software development are based on
automating the execution of scripts to minimize the chance of
introducing errors while developing applications. They require
less human intervention or even no intervention at all, from the
development of new code until its deployment.
It involves continuously building, testing, and deploying code
changes at every small iteration, reducing the chance of developing
new code based on bugged or failed previous versions.
There are three main approaches to this methodology, each of them
to be applied according to what best suits your strategy.
### Continuous Integration
Consider an application which has its code stored in a Git
repository in GitLab. Developers push code changes every day,
multiple times a day. For every push to the repository, you
can create a set of scripts to build and test your application
automatically, decreasing the chance of introducing errors to your app.
This practice is known as [Continuous Integration](;
for every change submitted to an application - even to development branches -
it's built and tested automatically and continuously, ensuring the
introduced changes pass all tests, guidelines, and code compliance
standards you established for your app.
[GitLab itself]( is an
example of using Continuous Integration as a software
development method. For every push to the project, there's a set
of scripts the code is checked against.
### Continuous Delivery
[Continuous Delivery]( is a step
beyond Continuous Integration. Your application is not only
built and tested at every code change pushed to the codebase,
but, as an additional step, it's also deployed continuously, though
the deployments are triggered manually.
This method ensures the code is checked automatically but requires
human intervention to manually and strategically trigger the deployment
of the changes.
### Continuous Deployment
[Continuous Deployment](
is also a further step beyond Continuous Integration, similar to
Continuous Delivery. The difference is that instead of deploying your
application manually, you set it to be deployed automatically. It does
not require human intervention at all to have your application
## Introduction to GitLab CI/CD
GitLab CI/CD is a powerful tool built into GitLab that allows you
to apply all the continuous methods (Continuous Integration,
Delivery, and Deployment) to your software with no third-party
application or integration needed.
### How GitLab CI/CD works
To use GitLab CI/CD, all you need is an application codebase hosted in a
Git repository, and for your build, test, and deployment
scripts to be specified in a file called [`.gitlab-ci.yml`](../yaml/,
located in the root path of your repository.
In this file, you can define the scripts you want to run, define include and
cache dependencies, choose what commands you want to run in sequence
and those you want to run in parallel, define where you want to
deploy your app, and choose if you want to run the script automatically
or if you want to trigger it manually. Once you're familiar with
GitLab CI/CD you can add more advanced steps into the configuration file.
To add scripts to that file, you'll need to organize them in a
sequence that suits your application and are in accordance with
the tests you wish to perform. To visualize the process, imagine
that all the scripts you add to the configuration file are the
same as the commands you run on a terminal in your computer.
Once you've added your `.gitlab-ci.yml` configuration file to your
repository, GitLab will detect it and run your scripts with the
tool called [GitLab Runner](, which
works similarly to your terminal.
The scripts are grouped into **jobs**, and together they compose
a **pipeline**. A minimalist example of `.gitlab-ci.yml` file
could contain:
- apt-get install rubygems ruby-dev -y
- ruby --version
The `before_script` attribute would install the dependencies
for your app before running anything, and a **job** called
`run-test` would print the Ruby version of the current system.
Both of them compose a **pipeline** triggered at every push
to any branch of the repository.
GitLab CI/CD not only executes the jobs you've
set, but also shows you what's happening during execution, as you
would see in your terminal:
![job running](img/job_running.png)
You create the strategy for your app and GitLab runs the pipeline
for you according to what you've defined. Your pipeline status is also
displayed by GitLab:
![pipeline status](img/pipeline_status.png)
At the end, if anything goes wrong, you can easily
[roll back](../ all the changes:
![rollback button](img/rollback.png)
### Basic CI/CD workflow
This is a very simple example for how GitLab CI/CD fits in a common
development workflow.
Assume that you have discussed a code implementation in an issue
and worked locally on your proposed changes. Once you push your
commits to a feature branch in a remote repository in GitLab,
the CI/CD pipeline set for your project is triggered. By doing
so, GitLab CI/CD:
- Runs automated scripts (sequential or parallel) to:
- Build and test your app.
- Deploy to a staging environment.
- Preview the changes per merge request with Review Apps, as you
would see in your `localhost`.
Once you're happy with your implementation:
- Get your code reviewed and approved.
- Merge the feature branch into the default branch.
- GitLab CI/CD deploys your changes automatically to a production environment.
- And finally, you and your team can easily roll it back if something goes wrong.
GitLab CI/CD is capable of a doing a lot more, but this workflow
exemplifies GitLab's ability to track the entire process,
without the need of any external tool to deliver your software.
And, most usefully, you can visualize all the steps through
the GitLab UI.
### Setting up GitLab CI/CD for the first time
To get started with GitLab CI/CD, you need to familiarize yourself
with the [`.gitlab-ci.yml`](../yaml/ configuration file
syntax and with its attributes.
This document [introduces the concepts of GitLab CI/CD in the scope of GitLab Pages](../../user/project/pages/, for deploying static websites.
Although it's meant for users who want to write their own Pages
script from scratch, it also serves as an introduction to the setup process for GitLab CI/CD.
It covers the very first general steps of writing a CI/CD configuration
file, so we recommend you read through it to understand GitLab's CI/CD
logic, and learn how to write your own script (or tweak an
existing one) for any application.
For an deep view of GitLab's CI/CD configuration options, check the
[`.gitlab-ci.yml` full reference](../yaml/
### GitLab CI/CD feature set
- Easily set up your app's entire lifecycle with [Auto DevOps](../../topics/autodevops/
- Deploy static websites with [GitLab Pages](../../user/project/pages/
- Deploy your app to different [environments](../
- Preview changes per merge request with [Review Apps](../review_apps/
- Develop secure and private Docker images with [Container Registry](../../user/project/
- Install your own [GitLab Runner](
- [Schedule pipelines](../../user/project/pipelines/
- Check for app vulnerabilities with [Security Test reports]( **[ULTIMATE]**
To see all CI/CD features, navigate back to the [CI/CD index](../
......@@ -9,14 +9,26 @@ date: 2017-02-22
# Creating and Tweaking GitLab CI/CD for GitLab Pages
[GitLab CI]( serves
To [get started with GitLab Pages](, you can
use one of the project templates, a `.gitlab-ci.yml` template,
or fork an existing example project. Therefore, you don't need to
understand _all_ the ins and odds of GitLab CI/CD to get your site
deployed. Still, there are cases where you want to write your own
script or tweak an existing one. This document guides you through
this process.
This guide also provides a general overview and clear introduction
for **getting familiar with the `.gitlab-ci.yml` file and writing
one for the first time.**
[GitLab CI/CD](../../../ci/ serves
numerous purposes, to build, test, and deploy your app
from GitLab through
[Continuous Integration, Continuous Delivery, and Continuous Deployment](
[Continuous Integration, Continuous Delivery, and Continuous Deployment](../../../ci/introduction/
methods. You will need it to build your website with GitLab Pages,
and deploy it to the Pages server.
To implement GitLab CI/CD, the first thing we need is a configuration
To implement GitLab CI/CD, the first thing you need is a configuration
file called `.gitlab-ci.yml` placed at your website's root directory.
What this file actually does is telling the
......@@ -26,7 +38,7 @@ terminal. GitLab CI/CD tells the Runner which commands to run.
Both are built-in in GitLab, and you don't need to set up
anything for them to work.
Explaining [every detail of GitLab CI](
Explaining [every detail of GitLab CI/CD](../../../ci/yaml/
and GitLab Runner is out of the scope of this guide, but we'll
need to understand just a few things to be able to write our own
`.gitlab-ci.yml` or tweak an existing one. It's an
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment