diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-18 06:09:21 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-18 06:09:21 +0300 |
commit | cfaf98a3b214c773f058ed9648314e4f147bbba4 (patch) | |
tree | c02a6855511a65696890c21270da5911896beff2 /doc/ci/quick_start | |
parent | c48065a833f9ead3357c48ea077165c15e8d585c (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/ci/quick_start')
-rw-r--r-- | doc/ci/quick_start/README.md | 276 | ||||
-rw-r--r-- | doc/ci/quick_start/img/build_log.png | bin | 138388 -> 0 bytes | |||
-rw-r--r-- | doc/ci/quick_start/img/builds_status.png | bin | 47887 -> 0 bytes | |||
-rw-r--r-- | doc/ci/quick_start/img/job_details_v13_6.png | bin | 0 -> 127827 bytes | |||
-rw-r--r-- | doc/ci/quick_start/img/new_commit.png | bin | 5541 -> 0 bytes | |||
-rw-r--r-- | doc/ci/quick_start/img/new_file_v13_6.png | bin | 0 -> 9653 bytes | |||
-rw-r--r-- | doc/ci/quick_start/img/pipeline_graph_v13_6.png | bin | 0 -> 27157 bytes | |||
-rw-r--r-- | doc/ci/quick_start/img/pipelines_status.png | bin | 64605 -> 0 bytes | |||
-rw-r--r-- | doc/ci/quick_start/img/single_commit_status_pending.png | bin | 13631 -> 0 bytes | |||
-rw-r--r-- | doc/ci/quick_start/img/three_stages_v13_6.png | bin | 0 -> 23531 bytes |
10 files changed, 100 insertions, 176 deletions
diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 9db42538092..f3e60fae13a 100644 --- a/doc/ci/quick_start/README.md +++ b/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 +To create a `.gitlab-ci.yml` file: -rubocop: - script: - - bundle exec rubocop -``` +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**: -This is the simplest possible configuration that will work for most Ruby -applications: + ![New file](img/new_file_v13_6.png) -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. +1. For the **File name** type `.gitlab-ci.yml` and in the larger window, + paste this sample code: -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. + ```yaml + build-job: + stage: build + script: + - echo "Hello, $GITLAB_USER_LOGIN!" -What is important is that each job is run independently from each other. + test-job1: + stage: test + script: + - echo "This job tests something" -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. + 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 -You can use the [CI/CD configuration visualization](../yaml/visualization.md) to -see a graphical representation of your `.gitlab-ci.yml`. + deploy-prod: + stage: deploy + script: + - echo "This job deploys something from the $CI_COMMIT_BRANCH branch." + ``` -For more information and a complete `.gitlab-ci.yml` syntax, please read -[the reference documentation on `.gitlab-ci.yml`](../yaml/README.md). + `$GITLAB_USER_LOGIN` and `$CI_COMMIT_BRANCH` are + [predefined variables](../variables/predefined_variables.md) + that populate when the job runs. -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. +1. Click **Commit changes**. -### Push `.gitlab-ci.yml` to GitLab +The pipeline starts when the commit is committed. -After you've created a `.gitlab-ci.yml`, you should add it to your Git repository -and push it to GitLab. +#### `.gitlab-ci.yml` tips -```shell -git add .gitlab-ci.yml -git commit -m "Add .gitlab-ci.yml" -git push origin master -``` +- 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: -Now if you go to the **Pipelines** page you will see that the pipeline is -pending. + ```yaml + default: + image: ruby:2.7.2 + ``` -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**. + This command tells the runner to use a Ruby image from Docker Hub. -You can also go to the **Commits** page and notice the little pause icon next -to the commit SHA. +- 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). -![New commit pending](img/new_commit.png) +### View the status of your pipeline and jobs -Clicking on it you will be directed to the jobs page for that specific commit. +When you committed your changes, a pipeline started. -![Single commit jobs page](img/single_commit_status_pending.png) +To view your pipeline: -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. +- Go **CI/CD > Pipelines**. -The next step is to configure a runner so that it picks the pending jobs. + A pipeline with three stages should be displayed: -## Configuring a runner + ![Three stages](img/three_stages_v13_6.png) -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. +- To view a visual representation of your pipeline, click the pipeline ID. -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_. + ![Pipeline graph](img/pipeline_graph_v13_6.png) -Find more information about runners in the -[runner](../runners/README.md) documentation. +- To view details of a job, click the job name, for example, `deploy-prod`. -The official runner supported by GitLab is written in Go. -View [the documentation](https://docs.gitlab.com/runner/). + ![Job details](img/job_details_v13_6.png) -For a runner to be available in GitLab, you must: - -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/). - -When a runner is available, you can view it by -clicking **Settings > CI/CD** and expanding **Runners**. - -![Activated runners](img/runners_activated.png) - -### Shared runners - -If you use [GitLab.com](https://gitlab.com/), you can use the **shared runners** -provided by GitLab. - -These are special virtual machines that run on GitLab's infrastructure and can -build any project. - -To enable shared runners, go to your project's or group's -**Settings > CI/CD** and click **Enable shared runners**. - -[Read more about shared runners](../runners/README.md#shared-runners). - -## Viewing the status of your pipeline and jobs - -After configuring the runner successfully, you should see the status of your -last commit change from _pending_ to either _running_, _success_ or _failed_. - -You can view all pipelines by going to the **Pipelines** page in your project. - -![Commit status](img/pipelines_status.png) - -Or you can view all jobs, by going to the **Pipelines ➔ Jobs** page. - -![Commit status](img/builds_status.png) - -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. - -![Build log](img/build_log.png) - -You are also able to view the status of any commit in the various pages in -GitLab, such as **Commits** and **Merge requests**. - -## Additional resources - -Visit the [examples README](../examples/README.md) to see a list of examples using GitLab -CI with various languages. - -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. diff --git a/doc/ci/quick_start/img/build_log.png b/doc/ci/quick_start/img/build_log.png Binary files differdeleted file mode 100644 index 16698629edc..00000000000 --- a/doc/ci/quick_start/img/build_log.png +++ /dev/null diff --git a/doc/ci/quick_start/img/builds_status.png b/doc/ci/quick_start/img/builds_status.png Binary files differdeleted file mode 100644 index b4aeeb988d2..00000000000 --- a/doc/ci/quick_start/img/builds_status.png +++ /dev/null diff --git a/doc/ci/quick_start/img/job_details_v13_6.png b/doc/ci/quick_start/img/job_details_v13_6.png Binary files differnew file mode 100644 index 00000000000..e94287f90ba --- /dev/null +++ b/doc/ci/quick_start/img/job_details_v13_6.png diff --git a/doc/ci/quick_start/img/new_commit.png b/doc/ci/quick_start/img/new_commit.png Binary files differdeleted file mode 100644 index 507eb93ac0c..00000000000 --- a/doc/ci/quick_start/img/new_commit.png +++ /dev/null diff --git a/doc/ci/quick_start/img/new_file_v13_6.png b/doc/ci/quick_start/img/new_file_v13_6.png Binary files differnew file mode 100644 index 00000000000..c71923f9b90 --- /dev/null +++ b/doc/ci/quick_start/img/new_file_v13_6.png diff --git a/doc/ci/quick_start/img/pipeline_graph_v13_6.png b/doc/ci/quick_start/img/pipeline_graph_v13_6.png Binary files differnew file mode 100644 index 00000000000..fcf7e02d1f3 --- /dev/null +++ b/doc/ci/quick_start/img/pipeline_graph_v13_6.png diff --git a/doc/ci/quick_start/img/pipelines_status.png b/doc/ci/quick_start/img/pipelines_status.png Binary files differdeleted file mode 100644 index 39a77a26b25..00000000000 --- a/doc/ci/quick_start/img/pipelines_status.png +++ /dev/null diff --git a/doc/ci/quick_start/img/single_commit_status_pending.png b/doc/ci/quick_start/img/single_commit_status_pending.png Binary files differdeleted file mode 100644 index ffc7054d3b0..00000000000 --- a/doc/ci/quick_start/img/single_commit_status_pending.png +++ /dev/null diff --git a/doc/ci/quick_start/img/three_stages_v13_6.png b/doc/ci/quick_start/img/three_stages_v13_6.png Binary files differnew file mode 100644 index 00000000000..a6c049e3e6c --- /dev/null +++ b/doc/ci/quick_start/img/three_stages_v13_6.png |