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
This commit is contained in:
Mike Lewis
commit
90f4b6563d
7 changed files with 216 additions and 31 deletions
|
|
@ -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](../README.md#the-entire-devops-lifecycle), GitLab CI/CD spans
|
||||
the [Verify (CI)](../README.md#verify) and [Release (CD)](../README.md#release) 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](https://about.gitlab.com/product/continuous-integration/) 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/index.md). |
|
||||
| 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/README.md). |
|
||||
| A GitLab CI/CD expert | Jump straight to our [`.gitlab.yml`](yaml/README.md) reference. |
|
||||
|
||||
## Introduction
|
||||
|
||||
The following introduces the process of continuous integration (CI) and continuous delivery (CD):
|
||||
|
||||
|
||||
|
||||
In this illustration:
|
||||
|
||||
- New code is combined with existing code through a commit to a project's [repository](../user/project/repository/index.md).
|
||||
- The newly combined code is sent to a CI [pipeline](pipelines.md) where:
|
||||
- The code is [built](../user/project/pipelines/job_artifacts.md).
|
||||
- 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/index.md).
|
||||
- Deploying to configured [environments](environments.md).
|
||||
|
||||
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](../README.md#the-entire-devops-lifecycle), GitLab CI/CD spans
|
||||
the [Verify (CI)](../README.md#verify) and [Release (CD)](../README.md#release) 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/README.md) | Outlines the first steps for configuring GitLab CI/CD. |
|
||||
| [Introduction to pipelines and jobs](pipelines.md) | Provides an overview of GitLab CI/CD and jobs. |
|
||||
| [Configuration of your pipelines with `.gitlab-ci.yml`](yaml/README.md) | A comprehensive reference for the `.gitlab-ci.yml` file. |
|
||||
| [`.gitlab-ci.yml` introduction](../user/project/pages/getting_started_part_four.md) | 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](https://docs.gitlab.com/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/index.md).
|
||||
documentation on [GitLab Pages](../user/project/pages/index.md),
|
||||
or dive right into the [CI/CD step-by-step guide for Pages](../user/project/pages/getting_started_part_four.md).
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 32 KiB |
BIN
doc/ci/introduction/img/job_running.png
Executable file
BIN
doc/ci/introduction/img/job_running.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 232 KiB |
BIN
doc/ci/introduction/img/pipeline_status.png
Executable file
BIN
doc/ci/introduction/img/pipeline_status.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
BIN
doc/ci/introduction/img/rollback.png
Executable file
BIN
doc/ci/introduction/img/rollback.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
192
doc/ci/introduction/index.md
Normal file
192
doc/ci/introduction/index.md
Normal file
|
|
@ -0,0 +1,192 @@
|
|||
---
|
||||
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](https://en.wikipedia.org/wiki/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](https://gitlab.com/gitlab-org/gitlab-ce) 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](https://continuousdelivery.com/) 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](https://www.airpair.com/continuous-deployment/posts/continuous-deployment-for-practical-people)
|
||||
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
|
||||
deployed.
|
||||
|
||||
## 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/README.md),
|
||||
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](https://docs.gitlab.com/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:
|
||||
|
||||
```yml
|
||||
before_script:
|
||||
- apt-get install rubygems ruby-dev -y
|
||||
|
||||
run-test:
|
||||
script:
|
||||
- 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:
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
At the end, if anything goes wrong, you can easily
|
||||
[roll back](../environments.md#rolling-back-changes) all the changes:
|
||||
|
||||
|
||||
|
||||
### 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/README.md) 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/getting_started_part_four.md), 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/README.md).
|
||||
|
||||
### GitLab CI/CD feature set
|
||||
|
||||
- Easily set up your app's entire lifecycle with [Auto DevOps](../../topics/autodevops/index.md).
|
||||
- Deploy static websites with [GitLab Pages](../../user/project/pages/index.md).
|
||||
- Deploy your app to different [environments](../environments.md).
|
||||
- Preview changes per merge request with [Review Apps](../review_apps/index.md).
|
||||
- Develop secure and private Docker images with [Container Registry](../../user/project/container_registry.md).
|
||||
- Install your own [GitLab Runner](https://docs.gitlab.com/runner/).
|
||||
- [Schedule pipelines](../../user/project/pipelines/schedules.md).
|
||||
- Check for app vulnerabilities with [Security Test reports](https://docs.gitlab.com/ee/user/project/merge_requests/#security-reports-ultimate). **[ULTIMATE]**
|
||||
|
||||
To see all CI/CD features, navigate back to the [CI/CD index](../README.md).
|
||||
|
|
@ -9,14 +9,26 @@ date: 2017-02-22
|
|||
|
||||
# Creating and Tweaking GitLab CI/CD for GitLab Pages
|
||||
|
||||
[GitLab CI](https://about.gitlab.com/gitlab-ci/) serves
|
||||
To [get started with GitLab Pages](index.md#getting-started), 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/README.md) serves
|
||||
numerous purposes, to build, test, and deploy your app
|
||||
from GitLab through
|
||||
[Continuous Integration, Continuous Delivery, and Continuous Deployment](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/)
|
||||
[Continuous Integration, Continuous Delivery, and Continuous Deployment](../../../ci/introduction/index.md#introduction-to-continuous-methods)
|
||||
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](https://docs.gitlab.com/ce/ci/yaml/README.html)
|
||||
Explaining [every detail of GitLab CI/CD](../../../ci/yaml/README.md)
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue