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

7 files changed, 216 insertions, 31 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index 4c3c9920b93..ab77c63f794 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -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):
-
-![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/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
 
diff --git a/doc/ci/img/cicd_pipeline_infograph.png b/doc/ci/img/cicd_pipeline_infograph.png
deleted file mode 100644
index 9ddd4aa828b..00000000000
--- a/doc/ci/img/cicd_pipeline_infograph.png
+++ /dev/null
diff --git a/doc/ci/introduction/img/job_running.png b/doc/ci/introduction/img/job_running.png
new file mode 100755
index 00000000000..d5f922ceb8c
--- /dev/null
+++ b/doc/ci/introduction/img/job_running.png
diff --git a/doc/ci/introduction/img/pipeline_status.png b/doc/ci/introduction/img/pipeline_status.png
new file mode 100755
index 00000000000..96881f072e1
--- /dev/null
+++ b/doc/ci/introduction/img/pipeline_status.png
diff --git a/doc/ci/introduction/img/rollback.png b/doc/ci/introduction/img/rollback.png
new file mode 100755
index 00000000000..38e0552f4f1
--- /dev/null
+++ b/doc/ci/introduction/img/rollback.png
diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md
new file mode 100644
index 00000000000..eeb89f80e09
--- /dev/null
+++ b/doc/ci/introduction/index.md
@@ -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:
+
+![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](../environments.md#rolling-back-changes) 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/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).
diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md
index 05d5a2fd99a..021139d486d 100644
--- a/doc/user/project/pages/getting_started_part_four.md
+++ b/doc/user/project/pages/getting_started_part_four.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