For an overview, see [Introduction to GitLab CI](https://www.youtube.com/watch?v=l5705U8s_nQ&t=397) from a recent GitLab meetup.
### 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 commands you want to run in sequence
and those you want to run in parallel, define where you want to
deploy your app, and specify whether you want to run the scripts automatically
or trigger any of them manually. After you're familiar with
GitLab CI/CD you can add more advanced steps into the configuration file.
To add scripts to that file, you 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 on your computer.
After you've added your `.gitlab-ci.yml` configuration file to your
repository, GitLab detects 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:
```yaml
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:
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:
At the end, if anything goes wrong, you can easily
[roll back](../environments/index.md#retrying-and-rolling-back) all the changes:
### Basic CI/CD workflow
Consider the following example for how GitLab CI/CD fits in a
...
...
@@ -202,16 +141,14 @@ according to each stage (Verify, Package, Release).
- Perform a series of tests, such as [Container Scanning](../../user/application_security/container_scanning/index.md)**(ULTIMATE)**, [Dependency Scanning](../../user/application_security/dependency_scanning/index.md)**(ULTIMATE)**, and [Unit tests](../unit_test_reports.md).
- Deploy your changes with [Review Apps](../review_apps/index.md) to preview the app changes on every branch.
1.**Package**:
- Store Docker images with [Container Registry](../../user/packages/container_registry/index.md).
- Store NPM packages with [NPM Registry](../../user/packages/npm_registry/index.md). **(PREMIUM)**
- Store Maven artifacts with [Maven Repository](../../user/packages/maven_repository/index.md). **(PREMIUM)**
- Store Conan packages with [Conan Repository](../../user/packages/conan_repository/index.md). **(PREMIUM)**
- Store Docker images with the [Container Registry](../../user/packages/container_registry/index.md).
- Store packages with the [Package Registry](../../user/packages/package_registry/index.md).
1.**Release**:
- Continuous Deployment, automatically deploying your app to production.
- Continuous Delivery, manually click to deploy your app to production.
- Deploy static websites with [GitLab Pages](../../user/project/pages/index.md).
- Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature with [Canary Deployments](../../user/project/canary_deployments.md). **(PREMIUM)**
- Deploy your features behind [Feature Flags](../../operations/feature_flags.md).**(PREMIUM)**
- Deploy your features behind [Feature Flags](../../operations/feature_flags.md).
- Add release notes to any Git tag with [GitLab Releases](../../user/project/releases/index.md).
- View of the current health and status of each CI environment running on Kubernetes with [Deploy Boards](../../user/project/deploy_boards.md). **(PREMIUM)**
- Deploy your application to a production environment in a Kubernetes cluster with [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy).
...
...
@@ -228,23 +165,3 @@ To see all CI/CD features, navigate back to the [CI/CD index](../README.md).
Watch the video [GitLab CI Live Demo](https://youtu.be/l5705U8s_nQ?t=369) with a deeper overview of GitLab CI/CD.
### 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/pages_from_scratch.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 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 a deep view of GitLab's CI/CD configuration options, check the
[`.gitlab-ci.yml` full reference](../yaml/README.md).
For help making your pipelines faster and more efficient, see the
info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
type:reference
---
<!-- markdownlint-disable MD044 -->
# The .gitlab-ci.yml file
<!-- markdownlint-enable MD044 -->
To use GitLab CI/CD, you need 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`](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 commands you want to run in sequence
and those you want to run in parallel, define where you want to
deploy your app, and specify whether you want to run the scripts automatically
or trigger any of them manually. After you're familiar with
GitLab CI/CD you can add more advanced steps into the configuration file.
To add scripts to that file, you 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 on your computer.
After you've added your `.gitlab-ci.yml` configuration file to your
repository, GitLab detects 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:
```yaml
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:
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:
At the end, if anything goes wrong, you can easily
[roll back](../environments/index.md#retrying-and-rolling-back) all the changes:
[View the full syntax for the `.gitlab-ci.yml` file](README.md).
