Merge branch 'docs-ssot-review-ci-examples' into 'master'

Update CI Examples section to confirm to SSOT Documentation standards

Closes #61507

See merge request gitlab-org/gitlab-ce!29397

doc/ci/README.md

@@ -127,12 +127,10 @@ Its feature set is listed on the table below according to DevOps stages.
 
 ## Examples
 
-GitLab provides examples of configuring GitLab CI/CD in the form of:
+Find example project code and tutorials for using GitLab CI/CD with a variety of app frameworks, languages, and platforms
+on the [CI Examples](examples/README.md) page.
 
-- A collection of [examples and other resources](examples/README.md).
-- Example projects that are available at the [`gitlab-examples`](https://gitlab.com/gitlab-examples) group. For example, see:
-  - [`multi-project-pipelines`](https://gitlab.com/gitlab-examples/multi-project-pipelines) for examples of implementing multi-project pipelines.
-  - [`review-apps-nginx`](https://gitlab.com/gitlab-examples/review-apps-nginx/) provides an example of using Review Apps.
+GitLab also provides [example projects](https://gitlab.com/gitlab-examples) pre-configured to use GitLab CI/CD.
 
 ## Administration **[CORE ONLY]**
 

doc/ci/examples/artifactory_and_gitlab/index.md

@@ -4,6 +4,7 @@ author: Fabio Busatto
 author_gitlab: bikebilly
 level: intermediate
 article_type: tutorial
+type: tutorial
 date: 2017-08-15
 ---
 
@@ -16,8 +17,8 @@ to build a [Maven](https://maven.apache.org/) project, deploy it to [Artifactory
 
 You'll create two different projects:
 
-- `simple-maven-dep`: the app built and deployed to Artifactory (available at <https://gitlab.com/gitlab-examples/maven/simple-maven-dep>)
-- `simple-maven-app`: the app using the previous one as a dependency (available at <https://gitlab.com/gitlab-examples/maven/simple-maven-app>)
+- `simple-maven-dep`: the app built and deployed to Artifactory (see the [simple-maven-dep](https://gitlab.com/gitlab-examples/maven/simple-maven-dep) example project)
+- `simple-maven-app`: the app using the previous one as a dependency (see the [simple-maven-app](https://gitlab.com/gitlab-examples/maven/simple-maven-app) example project)
 
 We assume that you already have a GitLab account on [GitLab.com](https://gitlab.com/), and that you know the basic usage of Git and [GitLab CI/CD](https://about.gitlab.com/product/continuous-integration/).
 We also assume that an Artifactory instance is available and reachable from the internet, and that you have valid credentials to deploy on it.

doc/ci/examples/browser_performance.md

-# Browser Performance Testing with the Sitespeed.io container
+---
+type: howto
+---
 
-CAUTION: **Caution:**
+# Browser Performance Testing with the sitespeed.io container
+
+NOTE: **Note:**
 The job definition shown below is supported on GitLab 11.5 and later versions.
 It also requires the GitLab Runner 11.5 or later.
 For earlier versions, use the [previous job definitions](#previous-job-definitions).
 
 This example shows how to run the
-[Sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/) on
-your code by using GitLab CI/CD and [Sitespeed.io](https://www.sitespeed.io)
+[sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/) on
+your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io)
 using Docker-in-Docker.
 
 First, you need GitLab Runner with
@@ -38,20 +42,20 @@ performance:
 ```
 
 The above example will create a `performance` job in your CI/CD pipeline and will run
-Sitespeed.io against the webpage you defined in `URL` to gather key metrics.
+sitespeed.io against the webpage you defined in `URL` to gather key metrics.
 The [GitLab plugin](https://gitlab.com/gitlab-org/gl-performance) for
-Sitespeed.io is downloaded in order to save the report as a
+sitespeed.io is downloaded in order to save the report as a
 [Performance report artifact](../yaml/README.md#artifactsreportsperformance-premium)
 that you can later download and analyze.
 Due to implementation limitations we always take the latest Performance artifact available.
 
-The full HTML Sitespeed.io report will also be saved as an artifact, and if you have
+The full HTML sitespeed.io report will also be saved as an artifact, and if you have
 [GitLab Pages](../../user/project/pages/index.md) enabled, it can be viewed
 directly in your browser.
 
-For further customization options of Sitespeed.io, including the ability to
-provide a list of URLs to test, please consult
-[their documentation](https://www.sitespeed.io/documentation/sitespeed.io/configuration/).
+For further customization options for sitespeed.io, including the ability to
+provide a list of URLs to test, please see the
+[Sitespeed.io Configuration](https://www.sitespeed.io/documentation/sitespeed.io/configuration/) documentation.
 
 TIP: **Tip:**
 For [GitLab Premium](https://about.gitlab.com/pricing/) users, key metrics are automatically
@@ -73,7 +77,7 @@ set this up:
 1. In the `performance` job, read the previous artifact into an environment
    variable, like `$CI_ENVIRONMENT_URL`, and use it to parameterize the test
    URLs.
-1. You can now run the Sitespeed.io container against the desired hostname and
+1. You can now run the sitespeed.io container against the desired hostname and
    paths.
 
 Your `.gitlab-ci.yml` file would look like:

doc/ci/examples/code_quality.md

+---
+type: reference, howto
+---
+
 # Analyze your project's Code Quality
 
 CAUTION: **Caution:**

doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md

@@ -3,6 +3,7 @@ author: Dylan Griffith
 author_gitlab: DylanGriffith
 level: intermediate
 article_type: tutorial
+type: tutorial
 date: 2018-06-07
 last_updated: 2019-04-08
 description: "Continuous Deployment of a Spring Boot application to Cloud Foundry with GitLab CI/CD"
@@ -26,13 +27,13 @@ using GitLab CI/CD, read through the blog post [Continuous Delivery of a Spring
 
 ## Requirements
 
-_We assume you are familiar with Java, GitLab, Cloud Foundry, and GitLab CI/CD._
+This tutorial assumes you are familiar with Java, GitLab, Cloud Foundry, and GitLab CI/CD.
 
-To follow along with this tutorial you will need the following:
+To follow along, you will need:
 
 - An account on [Pivotal Web Services (PWS)](https://run.pivotal.io/) or any
-  other Cloud Foundry instance
-- An account on GitLab
+  other Cloud Foundry (CF) instance.
+- An account on GitLab.
 
 NOTE: **Note:**
 You will need to replace the `api.run.pivotal.io` URL in the all below

doc/ci/examples/deployment/README.md

+---
+type: tutorial
+---
+
 # Using Dpl as deployment tool
 
-[Dpl](https://github.com/travis-ci/dpl) (dee-pee-ell) is a deploy tool made for
+[Dpl](https://github.com/travis-ci/dpl) (prouncounced like the letters D-P-L) is a deploy tool made for
 continuous deployment that's developed and used by Travis CI, but can also be
 used with GitLab CI.
 
->**Note:**
-We recommend to use Dpl if you're deploying to any of these services:
-<https://github.com/travis-ci/dpl#supported-providers>.
+Dpl can be used to deploy to any of the [supported providers](https://github.com/travis-ci/dpl#supported-providers).
 
 ## Requirements
 
@@ -50,8 +52,8 @@ To use different provider take a look at long list of [Supported Providers](http
 
 ## Using Dpl with Docker
 
-When you use GitLab Runner you most likely configured it to use your server's shell commands.
-This means that all commands are run in context of local user (ie. gitlab_runner or gitlab_ci_multi_runner).
+In most cases, you will have configured [GitLab Runner](https://docs.gitlab.com/runner/) to use your server's shell commands.
+This means that all commands are run in the context of local user (e.g. gitlab_runner or gitlab_ci_multi_runner).
 It also means that most probably in your Docker container you don't have the Ruby runtime installed.
 You will have to install it:
 

doc/ci/examples/deployment/composer-npm-deploy.md

+---
+type: tutorial
+---
+
 # Running Composer and NPM scripts with deployment via SCP in GitLab CI/CD
 
-This guide covers the building dependencies of a PHP project while compiling assets via an NPM script.
+This guide covers the building of dependencies of a PHP project while compiling assets via an NPM script using [GitLab CI/CD](../../README.md).
 
-While is possible to create your own image with custom PHP and Node JS versions, for brevity, we will use an existing [Docker image](https://hub.docker.com/r/tetraweb/php/) that contains both PHP and NodeJS installed.
+While it is possible to create your own image with custom PHP and Node JS versions, for brevity, we will use an existing [Docker image](https://hub.docker.com/r/tetraweb/php/) that contains both PHP and NodeJS installed.
 
 ```yaml
 image: tetraweb/php
@@ -46,9 +50,9 @@ To make this work, you need to add a GitLab CI/CD Variable (accessible on _gitla
 
 ### Security tip
 
-Create a user that has access **only** to the folder that needs to be updated!
+Create a user that has access **only** to the folder that needs to be updated.
 
-After you create that variable, you need to make sure that key will be added to the docker container on run:
+After you create that variable, you need to make sure that key will be added to the Docker container on run:
 
 ```yaml
 before_script:
@@ -68,7 +72,7 @@ In order, this means that:
 
 And this is basically all you need in the `before_script` section.
 
-## How to deploy things
+## How to deploy
 
 As we stated above, we need to deploy the `build` folder from the docker image to our server. To do so, we create a new job:
 
@@ -93,7 +97,7 @@ Here's the breakdown:
 1. `ssh-add ...` we will add that private key you added on the web UI to the docker container
 1. We will connect via `ssh` and create a new `_tmp` folder
 1. We will connect via `scp` and upload the `build` folder (which was generated by a `npm` script) to our previously created `_tmp` folder
-1. We will connect again to `ssh` and move the `live` folder to an `_old` folder, then move `_tmp` to `live`.
+1. We will connect again via `ssh` and move the `live` folder to an `_old` folder, then move `_tmp` to `live`.
 1. We connect to ssh and remove the `_old` folder
 
 What's the deal with the artifacts? We just tell GitLab CI to keep the `build` directory (later on, you can download that as needed).
@@ -109,14 +113,14 @@ If you're using this only for stage server, you could do this in two steps:
 
 The problem is that there will be a small period of time when you won't have the app on your server.
 
-So we use so many steps because we want to make sure that at any given time we have a functional app in place.
+Therefore, for a production environment we use additional steps to ensure that at any given time, a functional app is in place.
 
 ## Where to go next
 
-Since this was a WordPress project, I gave real life code snippets. Some ideas you can pursuit:
+Since this was a WordPress project, I gave real life code snippets. Some further ideas you can pursue:
 
-- Having a slightly different script for `master` branch will allow you to deploy to a production server from that branch and to a stage server from any other branches;
-- Instead of pushing it live, you can push it to WordPress official repo (with creating a SVN commit & stuff);
+- Having a slightly different script for `master` branch will allow you to deploy to a production server from that branch and to a stage server from any other branches.
+- Instead of pushing it live, you can push it to WordPress official repo (with creating a SVN commit, etc.).
 - You could generate i18n text domains on the fly.
 
 ---

doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md

@@ -3,6 +3,7 @@ author: Ryan Hall
 author_gitlab: blitzgren
 level: intermediate
 article_type: tutorial
+type: tutorial
 date: 2018-03-07
 last_updated: 2019-03-11
 ---
@@ -14,7 +15,7 @@ platforms without the use of plugins like Adobe Flash. Furthermore, by using Git
 single game developers, as well as game dev teams, can easily host browser-based games online.
 
 In this tutorial, we'll focus on DevOps, as well as testing and hosting games with Continuous
-Integration/Deployment methods. We assume you are familiar with GitLab, javascript,
+Integration/Deployment methods using [GitLab CI/CD](../../README.md). We assume you are familiar with GitLab, JavaScript,
 and the basics of game development.
 
 ## The game

doc/ci/examples/end_to_end_testing_webdriverio/index.md

@@ -3,6 +3,7 @@ author: Vincent Tunru
 author_gitlab: Vinnl
 level: advanced
 article_type: user guide
+type: tutorial
 date: 2019-02-18
 description: 'Confidence checking your entire app every time a new feature is added can quickly become repetitive. Learn how to automate it with GitLab CI/CD.'
 ---
@@ -22,7 +23,9 @@ However, looking at the freshly deployed code to check whether it still looks an
 expected is repetitive manual work, which means it is a prime candidate for automation. This is
 where automated [end-to-end testing](https://martinfowler.com/bliki/BroadStackTest.html) comes in:
 having the computer run through a few simple scenarios that requires the proper functioning of all
-layers of your application, from the frontend to the database. In this article, we will discuss how
+layers of your application, from the frontend to the database.
+
+In this article, we will discuss how
 to write such end-to-end tests, and how to set up GitLab CI/CD to automatically run these tests
 against your new code, on a branch-by-branch basis. For the scope of this article, we will walk you
 through the process of setting up GitLab CI/CD for end-to-end testing Javascript-based applications

doc/ci/examples/laravel_with_gitlab_and_envoy/index.md

@@ -4,6 +4,7 @@ author: Mehran Rasulian
 author_gitlab: mehranrasulian
 level: intermediate
 article_type: tutorial
+type: tutorial
 date: 2017-08-31
 last_updated: 2019-03-06
 ---

doc/ci/examples/php.md

+---
+type: tutorial
+---
+
 # Testing PHP projects
 
 This guide covers basic building instructions for PHP projects.
 
-There are covered two cases: testing using the Docker executor and testing
+Two testing scenarios are covered: using the Docker executor and 
 using the Shell executor.
 
 ## Test PHP projects using the Docker executor
@@ -245,7 +249,7 @@ before_script:
 ...
 ```
 
-## Access private packages / dependencies
+## Access private packages or dependencies
 
 If your test suite needs to access a private repository, you need to configure
 [the SSH keys](../ssh_keys/README.md) in order to be able to clone it.
@@ -254,7 +258,7 @@ If your test suite needs to access a private repository, you need to configure
 
 Most of the time you will need a running database in order for your tests to
 run. If you are using the Docker executor you can leverage Docker's ability to
-link to other containers. In GitLab Runner lingo, this can be achieved by
+link to other containers. With GitLab Runner, this can be achieved by
 defining a `service`.
 
 This functionality is covered in [the CI services](../services/README.md)
@@ -279,7 +283,7 @@ We have set up an [Example PHP Project][php-example-repo] for your convenience
 that runs on [GitLab.com](https://gitlab.com) using our publicly available
 [shared runners](../runners/README.md).
 
-Want to hack on it? Simply fork it, commit and push  your changes. Within a few
+Want to hack on it? Simply fork it, commit, and push your changes. Within a few
 moments the changes will be picked by a public runner and the job will begin.
 
 [php-hub]: https://hub.docker.com/r/_/php/

doc/ci/examples/test-and-deploy-python-application-to-heroku.md

+---
+type: tutorial
+---
+
 # Test and deploy a Python application with GitLab CI/CD
 
 This example will guide you how to run tests in your Python application and deploy it automatically as Heroku application.
 
-You can checkout the [example source](https://gitlab.com/ayufan/python-getting-started).
+You can also view or fork the complete [example source](https://gitlab.com/ayufan/python-getting-started).
 
 ## Configure project
 
@@ -46,9 +50,9 @@ production:
 
 This project has three jobs:
 
-- `test` - used to test Django application,
-- `staging` - used to automatically deploy staging environment every push to `master` branch
-- `production` - used to automatically deploy production environment for every created tag
+- `test` - used to test Django application.
+- `staging` - used to automatically deploy staging environment every push to `master` branch.
+- `production` - used to automatically deploy production environment for every created tag.
 
 ## Store API keys
 
@@ -67,8 +71,9 @@ You can do this through the [Dashboard](https://dashboard.heroku.com/).
 ## Create Runner
 
 First install [Docker Engine](https://docs.docker.com/installation/).
+
 To build this project you also need to have [GitLab Runner](https://docs.gitlab.com/runner).
-You can use public runners available on `gitlab.com`, but you can register your own:
+You can use public runners available on `gitlab.com` or you can register your own:
 
 ```sh
 gitlab-runner register \
@@ -81,6 +86,6 @@ gitlab-runner register \
   --docker-postgres latest
 ```
 
-With the command above, you create a runner that uses [python:3.5](https://hub.docker.com/r/_/python/) image and uses [postgres](https://hub.docker.com/r/_/postgres/) database.
+With the command above, you create a runner that uses the [python:3.5](https://hub.docker.com/r/_/python/) image and uses a [postgres](https://hub.docker.com/r/_/postgres/) database.
 
-To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.
+To access the PostgreSQL database, connect to `host: postgres` as user `postgres` with no password.

doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md

+---
+type: tutorial
+---
+
 # Test and deploy a Ruby application with GitLab CI/CD
 
-This example will guide you how to run tests in your Ruby on Rails application and deploy it automatically as Heroku application.
+This example will guide you through how to run tests in your Ruby on Rails application and deploy it automatically as a Heroku application.
 
-You can checkout the example [source](https://gitlab.com/ayufan/ruby-getting-started) and check [CI status](https://gitlab.com/ayufan/ruby-getting-started/builds?scope=all).
+You can also view or fork the complete [example source](https://gitlab.com/ayufan/ruby-getting-started) and view the logs of its past [CI jobs](https://gitlab.com/ayufan/ruby-getting-started/-/jobs?scope=finished).
 
 ## Configure the project
 
@@ -53,13 +57,14 @@ Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/accoun
 ## Create Heroku application
 
 For each of your environments, you'll need to create a new Heroku application.
-You can do this through the [Dashboard](https://dashboard.heroku.com/).
+You can do this through the [Heroku Dashboard](https://dashboard.heroku.com/).
 
 ## Create Runner
 
 First install [Docker Engine](https://docs.docker.com/installation/).
+
 To build this project you also need to have [GitLab Runner](https://docs.gitlab.com/runner/).
-You can use public runners available on `gitlab.com`, but you can register your own:
+You can use public runners available on `gitlab.com` or register your own:
 
 ```sh
 gitlab-runner register \
@@ -72,6 +77,6 @@ gitlab-runner register \
   --docker-postgres latest
 ```
 
-With the command above, you create a Runner that uses [ruby:2.2](https://hub.docker.com/r/_/ruby/) image and uses [postgres](https://hub.docker.com/r/_/postgres/) database.
+With the command above, you create a Runner that uses the [ruby:2.2](https://hub.docker.com/r/_/ruby/) image and uses a [postgres](https://hub.docker.com/r/_/postgres/) database.
 
-To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.
+To access the PostgreSQL database, connect to `host: postgres` as user `postgres` with no password.

doc/ci/examples/test-clojure-application.md

+---
+type: tutorial
+---
+
+NOTE: **Note:**
+This document has not been updated recently and could be out of date. For the latest documentation, see the [GitLab CI/CD](../README.md) page and the [GitLab CI/CD Pipeline Configuration Reference](../yaml/README.md).
+
 # Test a Clojure application with GitLab CI/CD
 
-This example will guide you how to run tests in your Clojure application.
+This example will guide you how to run tests on your Clojure application.
 
-You can checkout the example [source](https://gitlab.com/dzaporozhets/clojure-web-application) and check [CI status](https://gitlab.com/dzaporozhets/clojure-web-application/builds?scope=all).
+You can view or fork the [example source](https://gitlab.com/dzaporozhets/clojure-web-application) and view the logs of its past [CI jobs](https://gitlab.com/dzaporozhets/clojure-web-application/builds?scope=finished).
 
 ## Configure the project
 
@@ -28,8 +35,9 @@ test:
     - lein test
 ```
 
-In before script we install JRE and [Leiningen](http://leiningen.org/).
-Sample project uses [migratus](https://github.com/yogthos/migratus) library to manage database migrations.
-So we added database migration as last step of `before_script` section
+In `before_script`, we install JRE and [Leiningen](http://leiningen.org/).
+
+The sample project uses the [migratus](https://github.com/yogthos/migratus) library to manage database migrations, and
+we have added a database migration as the last step of `before_script`.
 
-You can use public runners available on `gitlab.com` for testing your application with such configuration.
+You can use public runners available on `gitlab.com` for testing your application with this configuration.

doc/ci/examples/test-scala-application.md

+---
+type: tutorial
+---
+
 # Test and deploy a Scala application to Heroku
 
 This example demonstrates the integration of GitLab CI with Scala
-applications using SBT. Checkout the example
-[project](https://gitlab.com/gitlab-examples/scala-sbt) and
-[build status](https://gitlab.com/gitlab-examples/scala-sbt/builds).
+applications using SBT. You can view or fork the [example project](https://gitlab.com/gitlab-examples/scala-sbt)
+and view the logs of its past [CI jobs](https://gitlab.com/gitlab-examples/scala-sbt/-/jobs?scope=finished).
 
 ## Add `.gitlab-ci.yml` file to project
 
@@ -41,12 +44,14 @@ deploy:
     - dpl --provider=heroku --app=gitlab-play-sample-app --api-key=$HEROKU_API_KEY
 ```
 
-The `before_script` installs [SBT](http://www.scala-sbt.org/) and
-displays the version that is being used. The `test` stage executes SBT
-to compile and test the project.
-[scoverage](https://github.com/scoverage/sbt-scoverage) is used as an SBT
+In the above configuration:
+
+- The `before_script` installs [SBT](http://www.scala-sbt.org/) and
+displays the version that is being used.
+- The `test` stage executes SBT to compile and test the project.
+   - [sbt-scoverage](https://github.com/scoverage/sbt-scoverage) is used as an SBT
 plugin to measure test coverage.
-The `deploy` stage automatically deploys the project to Heroku using dpl.
+- The `deploy` stage automatically deploys the project to Heroku using dpl.
 
 You can use other versions of Scala and SBT by defining them in
 `build.sbt`.

doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md

@@ -3,6 +3,7 @@ author: Alexandre S Hostert
 author_gitlab: Hostert
 level: beginner
 article_type: tutorial
+type: tutorial
 date: 2018-02-20
 last_updated: 2019-03-06
 ---
@@ -16,11 +17,11 @@ simultaneous users.
 
 That's why we're hearing so much about Phoenix today.
 
-In this tutorial, we'll teach you how to set up GitLab CI/CD to build and test a Phoenix
+In this tutorial, we'll teach you how to set up [GitLab CI/CD](../../README.md) to build and test a Phoenix
 application.
 
-_We assume that you know how to create a Phoenix app, run tests locally, and how to work with Git
-and GitLab UI._
+The tutorial assumes that you know how to create a Phoenix app, run tests locally, and how to work with Git
+and the GitLab UI.
 
 ## Introduction