Merge branch 'selhorn-ci-quickstart' into 'master'

Docs: CI Get Started redo

See merge request gitlab-org/gitlab!47715

doc/ci/interactive_web_terminal/index.md

@@ -16,7 +16,7 @@ is deployed, some [security precautions](../../administration/integration/termin
 taken to protect the users.
 
 NOTE: **Note:**
-[Shared runners on GitLab.com](../quick_start/README.md#shared-runners) do not
+[Shared runners on GitLab.com](../runners/README.md#shared-runners) do not
 provide an interactive web terminal. Follow [this
 issue](https://gitlab.com/gitlab-org/gitlab/-/issues/24674) for progress on
 adding support. For groups and projects hosted on GitLab.com, interactive web

doc/ci/quick_start/README.md

@@ -5,229 +5,153 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 type: reference
 ---
 
-# Getting started with GitLab CI/CD
+# Get started with GitLab CI/CD
 
-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/index.md), you must:
+Use this document to get started with
+GitLab [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/).
 
-- 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).
+Before you start, make sure you have:
 
-The `.gitlab-ci.yml` file defines the structure and order of the pipelines, and determines:
+- A project in GitLab that you would like to use CI/CD for.
+- Maintainer or owner access for the project.
 
-- What to execute using [GitLab Runner](https://docs.gitlab.com/runner/).
-- What decisions to make when specific conditions are encountered. For example, when a process succeeds or fails.
+If you are migrating from another CI/CD tool, view this documentation:
 
-A simple pipeline commonly has
-three [stages](../yaml/README.md#stages):
+- [Migrate from CircleCI](../migration/circleci.md).
+- [Migrate from Jenkins](../migration/jenkins.md).
 
-- `build`
-- `test`
-- `deploy`
+## CI/CD process overview
 
-You do not need to use all three stages; stages with no jobs are ignored.
+To use GitLab CI/CD:
 
-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.
+1. [Ensure you have runners available](#ensure-you-have-runners-available) to run your jobs.
+   If you don't have a runner, [install GitLab Runner](https://docs.gitlab.com/runner/install/)
+   and [register a runner](https://docs.gitlab.com/runner/register/) for your instance, project, or group.
+1. [Create a `.gitlab-ci.yml` file](#create-a-gitlab-ciyml-file)
+   at the root of your repository. This file is where you define your CI/CD jobs.
 
-It's also common to use pipelines to automatically deploy
-tested code to staging and production environments.
+When you commit the file to your repository, the runner runs your jobs.
+The job results [are displayed in a pipeline](#view-the-status-of-your-pipeline-and-jobs).
 
-If you're already familiar with general CI/CD concepts, you can review which
-[pipeline architectures](../pipelines/pipeline_architectures.md) can be used
-in your projects. If you're coming over to GitLab from Jenkins, you can check out
-our [reference](../migration/jenkins.md) for converting your pre-existing pipelines
-over to our format.
+### Ensure you have runners available
 
-This guide assumes that you have:
+In GitLab, runners are agents that run your CI/CD jobs.
 
-- A working GitLab instance of version 8.0+ or are using
-  [GitLab.com](https://gitlab.com).
-- A project in GitLab that you would like to use CI for.
-- Maintainer or owner access to the project
+You might already have runners available for your project, including
+[shared runners](../runners/README.md#shared-runners), which are
+available to all projects in your GitLab instance.
 
-Let's break it down to pieces and work on solving the GitLab CI/CD puzzle.
+To view available runners:
 
-## Creating a `.gitlab-ci.yml` file
+- Go to **Settings > CI/CD** and expand **Runners**.
 
-Before you create `.gitlab-ci.yml` let's first explain in brief what this is
-all about.
+As long as you have at least one runner that's active, with a green circle next to it,
+you have a runner available to process your jobs.
 
-### What is `.gitlab-ci.yml`
+If no runners are listed on the **Runners** page in the UI, you or an administrator
+must [install GitLab Runner](https://docs.gitlab.com/runner/install/) and
+[register](https://docs.gitlab.com/runner/register/) at least one runner.
 
-The `.gitlab-ci.yml` file is where you configure what CI does with your project.
-It lives in the root of your repository.
+If you are testing CI/CD, you can install GitLab Runner and register runners on your local machine.
+When your CI/CD jobs run, they will run on your local machine.
 
-On any push to your repository, GitLab will look for the `.gitlab-ci.yml`
-file and start jobs on _runners_ according to the contents of the file,
-for that commit.
+### Create a `.gitlab-ci.yml` file
 
-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](https://about.gitlab.com/blog/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/).
+The `.gitlab-ci.yml` file is a [YAML](https://en.wikipedia.org/wiki/YAML) file where
+you configure specific instructions for GitLab CI/CD.
 
-### Creating a simple `.gitlab-ci.yml` file
+In this file, you define:
 
-You need to create a file named `.gitlab-ci.yml` in the root directory of your
-repository. This is a [YAML](https://en.wikipedia.org/wiki/YAML) file
-so you have to pay extra attention to indentation. Always use spaces, not tabs.
+- The structure and order of jobs that the runner should execute.
+- The decisions the runner should make when specific conditions are encountered.
 
-Below is an example for a Ruby on Rails project:
+For example, you might want to run a suite of tests when you commit to
+any branch except `master`. When you commit to `master`, you want
+to run the same suite, but also publish your application.
 
-```yaml
-default:
-  image: ruby:2.5
-  before_script:
-    - apt-get update
-    - apt-get install -y sqlite3 libsqlite3-dev nodejs
-    - ruby -v
-    - which ruby
-    - gem install bundler --no-document
-    - bundle install --jobs $(nproc) "${FLAGS[@]}"
+All of this is defined in the `.gitlab-ci.yml` file.
 
-rspec:
-  script:
-    - bundle exec rspec
-
-rubocop:
-  script:
-    - bundle exec rubocop
-```
-
-This is the simplest possible configuration that will work for most Ruby
-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.
-
-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.
-Jobs are used to create jobs, which are then picked by
-[runners](../runners/README.md) and executed within the environment of the runner.
-
-What is important is that each job is run independently from each other.
-
-If you want to check whether the `.gitlab-ci.yml` of your project is valid, there is a
-[CI Lint tool](../lint.md) available in every project.
-
-You can use the [CI/CD configuration visualization](../yaml/visualization.md) to
-see a graphical representation of your `.gitlab-ci.yml`.
-
-For more information and a complete `.gitlab-ci.yml` syntax, please read
-[the reference documentation on `.gitlab-ci.yml`](../yaml/README.md).
-
-TIP: **Tip:**
-A GitLab team member has made an [unofficial visual pipeline editor](https://unofficial.gitlab.tools/visual-pipelines/).
-There is a [plan to make it an official part of GitLab](https://gitlab.com/groups/gitlab-org/-/epics/4069)
-in the future, but it's available for anyone who wants to try it at the above link.
-
-### Push `.gitlab-ci.yml` to GitLab
-
-After you've created a `.gitlab-ci.yml`, you should add it to your Git repository
-and push it to GitLab.
+To create a `.gitlab-ci.yml` file:
 
-```shell
-git add .gitlab-ci.yml
-git commit -m "Add .gitlab-ci.yml"
-git push origin master
-```
+1. Go to **Project overview > Details**.
+1. Above the file list, select the branch you want to commit to,
+   click the plus icon, then select **New file**:
 
-Now if you go to the **Pipelines** page you will see that the pipeline is
-pending.
+   ![New file](img/new_file_v13_6.png)
 
-NOTE: **Note:**
-If you have a [mirrored repository where GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository),
-you may need to enable pipeline triggering in your project's
-**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.
+1. For the **File name** type `.gitlab-ci.yml` and in the larger window,
+   paste this sample code:
 
-You can also go to the **Commits** page and notice the little pause icon next
-to the commit SHA.
-
-![New commit pending](img/new_commit.png)
-
-Clicking on it you will be directed to the jobs page for that specific commit.
-
-![Single commit jobs page](img/single_commit_status_pending.png)
-
-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.
-
-The next step is to configure a runner so that it picks the pending jobs.
-
-## Configuring a runner
-
-In GitLab, runners run the jobs that you define in `.gitlab-ci.yml`. A runner
-can be a virtual machine, a VPS, a bare-metal machine, a Docker container, or
-even a cluster of containers. GitLab and the runner communicate through an API,
-so the only requirement is that the runner's machine has network access to the
-GitLab server.
-
-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 runners in the
-[runner](../runners/README.md) documentation.
+   ```yaml
+   build-job:
+     stage: build
+     script:
+       - echo "Hello, $GITLAB_USER_LOGIN!"
 
-The official runner supported by GitLab is written in Go.
-View [the documentation](https://docs.gitlab.com/runner/).
+   test-job1:
+     stage: test
+     script:
+       - echo "This job tests something"
 
-For a runner to be available in GitLab, you must:
+   test-job2:
+     stage: test
+     script:
+       - echo "This job tests something, but takes more time than test-job1."
+       - echo "After the echo commands complete, it runs the sleep command for 20 seconds"
+       - echo "which simulates a test that runs 20 seconds longer than test-job1"
+       - sleep 20
 
-1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/).
-1. [Register a runner for your group or project](https://docs.gitlab.com/runner/register/).
+   deploy-prod:
+     stage: deploy
+     script:
+       - echo "This job deploys something from the $CI_COMMIT_BRANCH branch."
+   ```
 
-When a runner is available, you can view it by
-clicking **Settings > CI/CD** and expanding **Runners**.
+   `$GITLAB_USER_LOGIN` and `$CI_COMMIT_BRANCH` are
+   [predefined variables](../variables/predefined_variables.md)
+   that populate when the job runs.
 
-![Activated runners](img/runners_activated.png)
+1. Click **Commit changes**.
 
-### Shared runners
+The pipeline starts when the commit is committed.
 
-If you use [GitLab.com](https://gitlab.com/), you can use the **shared runners**
-provided by GitLab.
+#### `.gitlab-ci.yml` tips
 
-These are special virtual machines that run on GitLab's infrastructure and can
-build any project.
+- If you want the runner to use a Docker image to run the jobs, edit the `.gitlab-ci.yml` file
+  to include your image name:
 
-To enable shared runners, go to your project's or group's
-**Settings > CI/CD** and click **Enable shared runners**.
+  ```yaml
+  default:
+    image: ruby:2.7.2
+  ```
 
-[Read more about shared runners](../runners/README.md#shared-runners).
+  This command tells the runner to use a Ruby image from Docker Hub.
 
-## Viewing the status of your pipeline and jobs
+- To validate your `.gitlab-ci.yml` file, use the
+  [CI Lint tool](../lint.md), which is available in every project.
+- You can also use [CI/CD configuration visualization](../yaml/visualization.md) to
+  view a graphical representation of your `.gitlab-ci.yml` file.
+- For the complete `.gitlab-ci.yml` syntax, see
+  [the `.gitlab-ci.yml` reference topic](../yaml/README.md).
 
-After configuring the runner successfully, you should see the status of your
-last commit change from _pending_ to either _running_, _success_ or _failed_.
+### View the status of your pipeline and jobs
 
-You can view all pipelines by going to the **Pipelines** page in your project.
+When you committed your changes, a pipeline started.
 
-![Commit status](img/pipelines_status.png)
+To view your pipeline:
 
-Or you can view all jobs, by going to the **Pipelines ➔ Jobs** page.
+- Go **CI/CD > Pipelines**.
 
-![Commit status](img/builds_status.png)
+  A pipeline with three stages should be displayed:
 
-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
-you expected.
+  ![Three stages](img/three_stages_v13_6.png)
 
-![Build log](img/build_log.png)
+- To view a visual representation of your pipeline, click the pipeline ID.
 
-You are also able to view the status of any commit in the various pages in
-GitLab, such as **Commits** and **Merge requests**.
+  ![Pipeline graph](img/pipeline_graph_v13_6.png)
 
-## Additional resources
+- To view details of a job, click the job name, for example, `deploy-prod`.
 
-Visit the [examples README](../examples/README.md) to see a list of examples using GitLab
-CI with various languages.
+  ![Job details](img/job_details_v13_6.png)
 
-For help making your new pipelines faster and more efficient, see the
-[pipeline efficiency documentation](../pipelines/pipeline_efficiency.md).
+If the job status is `stuck`, check to ensure a runner is probably configured for the project.