Skip to content

G
gitlab-ce
Commit 75cdf795 authored by Marcel Amirault's avatar Marcel Amirault
Browse files
Options

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

Docs: CI Get Started redo

See merge request gitlab-org/gitlab!47715
parents a61719f3 1d684fd4
Hide whitespace changes
Inline Side-by-side
Showing with 101 additions and 177 deletions
doc/ci/interactive_web_terminal/index.md
View file @ 75cdf795
......@@ -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
View file @ 75cdf795
......@@ -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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7