Commit f109d24d authored by Evan Read's avatar Evan Read

Merge branch 'docs-ci-index-refactor' into 'master'

Docs: Add intro and reorg CI index

Closes #58323

See merge request gitlab-org/gitlab-ce!27620
parents 5d5b9d57 9cff6716
......@@ -5,71 +5,113 @@ description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Inte
# GitLab Continuous Integration (GitLab CI/CD)
GitLab CI/CD is GitLab's built-in tool for software development using continuous methodology:
GitLab CI/CD is a tool built into GitLab for software development
through the [continuous methodologies](introduction/index.md#introduction-to-cicd-methodologies):
- Continuous integration (CI).
- Continuous delivery and deployment (CD).
Within the [DevOps lifecycle](../README.md#the-entire-devops-lifecycle), GitLab CI/CD spans
the [Verify (CI)](../README.md#verify) and [Release (CD)](../README.md#release) stages.
- Continuous Integration (CI)
- Continuous Delivery (CD)
- Continuous Deployment (CD)
## Overview
CI/CD is a vast area, so GitLab provides documentation for all levels of expertise. Consult the following table to find the right documentation for you:
Continuous Integration works by pushing small code chunks to your
application's code base hosted in a Git repository, and, to every
push, run a pipeline of scripts to build, test, and validate the
code changes before merging them into the main branch.
| Level of expertise | Resource |
|:------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------|
| New to the concepts of CI and CD | For a high-level overview, read an [introduction to CI/CD with GitLab](introduction/index.md). |
| Familiar with GitLab CI/CD concepts | After getting familiar with GitLab CI/CD, let us walk you through a simple example in our [getting started guide](quick_start/README.md). |
| A GitLab CI/CD expert | Jump straight to our [`.gitlab.yml`](yaml/README.md) reference. |
Continuous Delivery and Deployment consist of a step further CI,
deploying your application to production at every
push to the default branch of the repository.
Familiarity with GitLab Runner is also useful because it is responsible for running the jobs in your
CI/CD pipeline. On GitLab.com, shared Runners are enabled by default so you won't need to set this up to get started.
These methodologies allow you to catch bugs and errors early in
the development cycle, ensuring that all the code deployed to
production complies with the code standards you established for
your app.
## CI/CD with Auto DevOps
For a complete overview of these methodologies and GitLab CI/CD,
read the [Introduction to CI/CD with GitLab](introduction/index.md).
[Auto DevOps](../topics/autodevops/index.md) is the default minimum-configuration method for
implementing CI/CD. Auto DevOps:
## Getting started
- Provides simplified setup and execution of CI/CD.
- Allows GitLab to automatically detect, build, test, deploy, and monitor your applications.
GitLab CI/CD is configured by a file called `.gitlab-ci.yml` placed
at the repository's root. The scripts set in this file are executed
by the [GitLab Runner](https://docs.gitlab.com/runner/).
## Manually configured CI/CD
To get started with GitLab CI/CD, we recommend you read through
the following documents:
For complete control, you can manually configure GitLab CI/CD.
- [How GitLab CI/CD works](introduction/index.md#how-gitlab-cicd-works).
- [GitLab CI/CD basic workflow](introduction/index.md#basic-cicd-workflow).
- [Step-by-step guide for writing `.gitlab-ci.yml` for the first time](../user/project/pages/getting_started_part_four.md).
### Configuration and Usage
You can also get started by using one of the
[`.gitlab-ci.yml` templates](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates)
available through the UI. You can use them by creating a new file,
choosing a template that suits your application, and adjusting it
to your needs:
The following topics contain configuration and usage information for all features of GitLab CI/CD:
![Use a .gitlab-ci.yml template](img/add_file_template_11_10.png)
| Topic | Description |
|:--------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------|
| [Creating and using CI/CD pipelines](pipelines.md) | Understand, visualize, create, and use CI/CD pipelines. |
| [CI/CD Variables](variables/README.md) | Configuring and using environment variables in pipelines. |
| [Where variables can be used](variables/where_variables_can_be_used.md) | Where and how CI/CD variables can be used. |
| [User](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions | User access levels for performing certain CI actions. |
| [Configuring GitLab Runners](runners/README.md) | Configuring [GitLab Runner](https://docs.gitlab.com/runner/). |
| [Environments and deployments](environments.md) | Deploy the output of jobs into environments for reviewing, staging, and production. |
| [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes. |
| [Job artifacts](../user/project/pipelines/job_artifacts.md) | Using the output of jobs. |
| [Cache dependencies in GitLab CI/CD](caching/index.md) | Speed up pipelines using caching. |
| [Using Git submodules with GitLab CI](git_submodules.md) | How to run your CI jobs when using Git submodules. |
| [Using SSH keys with GitLab CI/CD](ssh_keys/README.md) | Use SSH keys in your build environment. |
| [Triggering pipelines through the API](triggers/README.md) | Use the GitLab API to trigger a pipeline. |
| [Connecting GitLab with a Kubernetes cluster](../user/project/clusters/index.md) | Integrate one or more Kubernetes clusters to your project. |
| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. |
| [Interactive web terminals](interactive_web_terminal/index.md) | Open an interactive web terminal to debug the running jobs. |
| [Optimizing GitLab for large repositories](large_repositories/index.md) | Useful tips on how to optimize GitLab and GitLab Runner for big repositories. |
| [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) **[PREMIUM]** | Check the current health and status of each CI/CD environment running on Kubernetes. |
| [GitLab CI/CD for external repositories](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html) **[PREMIUM]** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and BitBucket Cloud. |
For a broader overview, see the [CI/CD getting started](quick_start/README.md) guide.
Once you're familiar with how GitLab CI/CD works, see the
[`. gitlab-ci.yml` full reference](yaml/README.md)
for all the attributes you can set and use.
NOTE: **Note:**
GitLab CI/CD and [shared runners](runners/README.md#shared-specific-and-group-runners) are enabled in GitLab.com and available for all users, limited only to the [user's pipelines quota](https://docs.gitlab.com/ee/user/admin_area/settings/continuous_integration.html#extra-shared-runners-pipeline-minutes-quota).
## GitLab CI/CD configuration
GitLab CI/CD supports numerous configuration options:
| Configuration | Description |
|:--- |:--- |
| [Pipelines](pipelines.md) | Structure your CI/CD process through pipelines. |
| [Environment variables](variables/README.md) | Reuse values based on a variable/value key pair. |
| [Environments](environments.md) | Deploy your application to different environments (e.g., staging, production). |
| [Job artifacts](../user/project/pipelines/job_artifacts.md) | Output, use, and reuse job artifacts. |
| [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. |
| [Schedule pipelines](../user/project/pipelines/schedules.md) | Schedule pipelines to run as often as you need. |
| [Custom path for `.gitlab-ci.yml`](../user/project/pipelines/settings.md#custom-ci-config-path) | Define a custom path for the CI/CD configuration file. |
| [Git submodules for CI/CD](git_submodules.md) | Configure jobs for using Git submodules. |
| [SSH keys for CI/CD](ssh_keys/README.md) | Using SSH keys in your CI pipelines. |
| [Pipelines triggers](triggers/README.md) | Trigger pipelines through the API. |
| [Integrate with Kubernetes clusters](../user/project/clusters/index.md) | Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster. |
| [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own GitLab Runners to execute your scripts. |
| [Optimize GitLab and Runner for large repositories](large_repositories/index.md) | Recommended strategies for handling large repos. |
| [`.gitlab-ci.yml` full reference](yaml/README.md) | All the attributes you can use with GitLab CI/CD. |
Note that certain operations can only be performed according to the
[user](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions.
### GitLab Pages
## GitLab CI/CD feature set
GitLab CI/CD can be used to build and host static websites. For more information, see the
documentation on [GitLab Pages](../user/project/pages/index.md),
or dive right into the [CI/CD step-by-step guide for Pages](../user/project/pages/getting_started_part_four.md).
You can also use the vast GitLab CI/CD feature set to easily configure
it for specific purposes:
### Examples
| Feature | Description |
|:--- |:--- |
| [Auto Deploy](../topics/autodevops/index.md#auto-deploy) | Deploy your application to a production environment in a Kubernetes cluster. |
| [Auto DevOps](../topics/autodevops/index.md) | Set up your app's entire lifecycle. |
| [Building Docker images](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. |
| [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) **[PREMIUM]** | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. |
| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. |
| [CI services](services/README.md)| Link Docker containers with your base image. |
| [Container Scanning](https://docs.gitlab.com/ee/ci/examples/container_scanning.html) **[ULTIMATE]**| Check your Docker containers for known vulnerabilities. |
| [Dependency Scanning](https://docs.gitlab.com/ee/ci/examples/dependency_scanning.html) **[ULTIMATE]**| Analyze your dependencies for known vulnerabilities. |
| [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) **[PREMIUM]** | Check the current health and status of each CI/CD environment running on Kubernetes. |
| [Feature Flags](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html) **[PREMIUM]** | Deploy your features behind Feature Flags. |
| [GitLab CI/CD for external repositories](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/) **[PREMIUM]** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and BitBucket Cloud. |
| [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. |
| [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. |
| [Interactive Web Terminals](interactive_web_terminal/index.md) **[CORE ONLY]** | Open an interactive web terminal to debug the running jobs. |
| [JUnit tests](junit_test_reports.md)| Identify script failures directly on merge requests. |
| [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes. |
| [Security Test reports](https://docs.gitlab.com/ee/user/project/merge_requests/#security-reports-ultimate) **[ULTIMATE]** | Check for app vulnerabilities. |
| [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. |
## GitLab CI/CD examples
GitLab provides examples of configuring GitLab CI/CD in the form of:
......@@ -78,9 +120,10 @@ GitLab provides examples of configuring GitLab CI/CD in the form of:
- [`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.
### Administration
## GitLab CI/CD administration **[CORE ONLY]**
As a GitLab administrator, you can change the default behavior of GitLab CI/CD for:
As a GitLab administrator, you can change the default behavior
of GitLab CI/CD for:
- An [entire GitLab instance](../user/admin_area/settings/continuous_integration.md).
- Specific projects, using [pipelines settings](../user/project/pipelines/settings.md).
......@@ -90,33 +133,22 @@ See also:
- [How to enable or disable GitLab CI/CD](enable_or_disable_ci.md).
- Other [CI administration settings](../administration/index.md#continuous-integration-settings).
### Using Docker
Docker is commonly used with GitLab CI/CD. Learn more about how to to accomplish this with the following
documentation:
| Topic | Description |
|:-------------------------------------------------------------------------|:-------------------------------------------------------------------------|
| [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. |
| [Building Docker images with GitLab CI/CD](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. |
Related topics include:
- [Docker integration](docker/README.md).
- [CI services (linked Docker containers)](services/README.md).
## References
## Why GitLab CI/CD?
### Why GitLab CI/CD?
The following articles explain reasons to use GitLab CI/CD for your CI/CD infrastructure:
The following articles explain reasons to use GitLab CI/CD
for your CI/CD infrastructure:
- [Why we chose GitLab CI for our CI/CD solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/)
- [Building our web-app on GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/)
See also the [Why CI/CD?](https://docs.google.com/presentation/d/1OGgk2Tcxbpl7DJaIOzCX4Vqg3dlwfELC3u2jEeCBbDk) presentation.
## Breaking changes
### Breaking changes
As GitLab CI/CD has evolved, certain breaking changes have been necessary. These are:
As GitLab CI/CD has evolved, certain breaking changes have
been necessary. These are:
- [CI variables renaming for GitLab 9.0](variables/deprecated_variables.md#gitlab-90-renamed-variables). Read about the
deprecated CI variables and what you should use for GitLab 9.0+.
......
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