Commit d18d4530 authored by Marcel Amirault's avatar Marcel Amirault Committed by Achilleas Pipinellis
Browse files

Docs: Merge EE doc/user/project/*.md to CE

parent bda42da7fa5d
# Canary Deployments **[PREMIUM]**
> [Introduced][ee-1659] in [GitLab Premium][eep] 9.1.
A popular [Continuous Integration](
strategy, where a small portion of the fleet is updated to the new version of
your application.
## Overview
When embracing [Continuous Delivery][cd-blog], a company needs to decide what
type of deployment strategy to use. One of the most popular strategies is canary
deployments, where a small portion of the fleet is updated to the new version
first. This subset, the canaries, then serve as the proverbial
[canary in the coal mine](
If there is a problem with the new version of the application, only a small
percentage of users are affected and the change can either be fixed or quickly
Leveraging [Kubernetes' Canary deployments][kube-canary], visualize your canary
deployments right inside the [Deploy Board], without the need to leave GitLab.
## Use cases
Canary deployments can be used when you want to ship features to only a portion of
your pods fleet and watch their behavior as a percentage of your user base
visits the temporarily deployed feature. If all works well, you can deploy the
feature to production knowing that it won't cause any problems.
Canary deployments are also especially useful for backend refactors, performance
improvements, or other changes where the user interface doesn't change, but you
want to make sure the performance stays the same, or improves. Developers need
to be careful when using canaries with user-facing changes, because by default,
requests from the same user will be randomly distributed between canary and
non-canary pods, which could result in confusion or even errors. If needed, you
may want to consider [setting `service.spec.sessionAffinity` to `ClientIP` in
your Kubernetes service definitions][kube-net], but that is beyond the scope of
this document.
## Enabling Canary Deployments
Canary deployments require that you properly configure Deploy Boards:
1. Follow the steps to [enable Deploy Boards](
1. To track canary deployments you need to label your Kubernetes deployments and
pods with `track: canary`. To get started quickly, you can use the [Auto Deploy]
template for canary deployments that GitLab provides.
Depending on the deploy, the label should be either `stable` or `canary`.
Usually, `stable` and blank or missing label means the same thing, and `canary`
or any other track means canary/temporary.
This allows GitLab to discover whether deployment is stable or canary (temporary).
Once all of the above are set up and the pipeline has run at least once,
navigate to the environments page under **Pipelines > Environments**.
As the pipeline executes Deploy Boards will clearly mark canary pods, enabling
quick and easy insight into the status of each environment and deployment.
Canary deployments are marked with a yellow dot in the Deploy Board so that you
can easily notice them.
![Canary deployments on Deploy Board](img/deploy_boards_canary_deployments.png)
[autodeploy]: ../../ci/autodeploy/ "GitLab Autodeploy"
[deploy board]:
redirect_to: ''
This document was moved to [another location](
# Code Owners **[STARTER]**
> [Introduced](
in [GitLab Starter]( 11.3.
You can use a `CODEOWNERS` file to specify users that are responsible
for certain files in a repository.
You can choose and add the `CODEOWNERS` file in three places:
- to the root directory of the repository
- inside the `.gitlab/` directory
- inside the `docs/` directory
The `CODEOWNERS` file is scoped to a branch, which means that with the
introduction of new files, the person adding the new content can
specify themselves as a code owner, all before the new changes
get merged to the default branch.
When a file matches multiple entries in the `CODEOWNERS` file,
the users from all entries are displayed on the blob page of
the given file.
## The syntax of Code Owners files
Files can be specified using the same kind of patterns you would use
in the `.gitignore` file followed by the `@username` or email of one
or more users that should be owners of the file.
The order in which the paths are defined is significant: the last
pattern that matches a given path will be used to find the code
Starting a line with a `#` indicates a comment. This needs to be
escaped using `\#` to address files for which the name starts with a
Example `CODEOWNERS` file:
# This is an example code owners file, lines starting with a `#` will
# be ignored.
# app/ @commented-rule
# We can specifiy a default match using wildcards:
* @default-codeowner
# Rules defined later in the file take precedence over the rules
# defined before.
# This will match all files for which the file name ends in `.rb`
*.rb @ruby-owner
# Files with a `#` can still be accesssed by escaping the pound sign
\#file_with_pound.rb @owner-file-with-pound
# Multiple codeowners can be specified, separated by whitespace
CODEOWNERS @multiple @owners @tab-separated
# Both usernames or email addresses can be used to match
# users. Everything else will be ignored. For example this will
# specify `@legal` and a user with email `` as the
# owner for the LICENSE file
LICENSE @legal this_does_not_match
# Ending a path in a `/` will specify the code owners for every file
# nested in that directory, on any level
/docs/ @all-docs
# Ending a path in `/*` will specify code owners for every file in
# that directory, but not nested deeper. This will match
# `docs/` but not `docs/projects/`
/docs/* @root-docs
# This will make a `lib` directory nested anywhere in the repository
# match
lib/ @lib-owner
# This will only match a `config` directory in the root of the
# repository
/config/ @config-owner
# If the path contains spaces, these need to be escaped like this:
path\ with\ spaces/ @space-owner
# Deploy Boards **[PREMIUM]**
> [Introduced][ee-1589] in [GitLab Premium][ee] 9.0.
GitLab's Deploy Boards offer a consolidated view of the current health and
status of each CI [environment] running on [Kubernetes], displaying the status
of the pods in the deployment. Developers and other teammates can view the
progress and status of a rollout, pod by pod, in the workflow they already use
without any need to access Kubernetes.
## Overview
With Deploy Boards you can gain more insight into deploys with benefits such as:
- Following a deploy from the start, not just when it's done
- Watching the rollout of a build across multiple servers
- Finer state detail (Waiting, Deploying, Finished, Unknown)
- See [Canary Deployments](
Here's an example of a Deploy Board of the production environment.
![Deploy Boards landing page](img/deploy_boards_landing_page.png)
The squares represent pods in your Kubernetes cluster that are associated with
the given environment. Hovering above each square you can see the state of a
deploy rolling out. The percentage is the percent of the pods that are updated
to the latest release.
Since Deploy Boards are tightly coupled with Kubernetes, there is some required
knowledge. In particular you should be familiar with:
- [Kubernetes pods](
- [Kubernetes labels](
- [Kubernetes namespaces](
- [Kubernetes canary deployments](
## Use cases
Since the Deploy Board is a visual representation of the Kubernetes pods for a
specific environment, there are lot of uses cases. To name a few:
- You want to promote what's running in staging, to production. You go to the
environments list, verify that what's running in staging is what you think is
running, then click on the [manual action](../../ci/yaml/ to deploy to production.
- You trigger a deploy, and you've got lots of containers to upgrade so you know
it'll take a while (you've also throttled your deploy to only take down X
containers at a time). But you need to tell someone when it's deployed, so you
go to the environments list, look at the production environment to see what
the progress is in real-time as each pod is rolled.
- You get a report that something is weird in production, so you look at the
production environment to see what is running, and if a deploy is ongoing or
stuck or failed.
- You've got an MR that looks good, but you want to run it on staging because
staging is set up in some way closer to production. You go to the environment
list, find the [Review App][review apps] you're interested in, and click the
manual action to deploy it to staging.
## Enabling Deploy Boards
To display the Deploy Boards for a specific [environment] you should:
1. Have a Kubernetes cluster up and running.
NOTE: **Running on OpenShift:**
If you are using OpenShift, ensure that you're using the `Deployment` resource
instead of `DeploymentConfiguration`, otherwise the Deploy Boards won't render
correctly. For more information, read the
[OpenShift docs](
and [GitLab issue #4584](
1. [Configure GitLab Runner][runners] with the [Docker][docker-exec] or
[Kubernetes][kube-exec] executor.
1. Configure the [Kubernetes service][kube-service] in your project for the
cluster. The Kubernetes namespace is of particular note as you will need it
for your deployment scripts (exposed by the `KUBE_NAMESPACE` env variable).
1. Ensure Kubernetes annotations of ` $CI_ENVIRONMENT_SLUG`
and ` $CI_PROJECT_PATH_SLUG` are applied to the
deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` and
`$CI_PROJECT_PATH_SLUG` are the values of the CI variables. This is so we can
lookup the proper environment in a cluster/namespace which may have more
than one. These resources should be contained in the namespace defined in
the Kubernetes service setting. You can use an [Autodeploy] `.gitlab-ci.yml`
template which has predefined stages and commands to use, and automatically
applies the annotations. Each project will need to have a unique namespace in
Kubernetes as well. The image below demonstrates how this is shown inside
NOTE: **Note:**
The Kubernetes label of `app` is deprecated and may be removed in next major
release, GitLab 12.0.
![Deploy Boards Kubernetes Label](img/deploy_boards_kubernetes_label.png)
Once all of the above are set up and the pipeline has run at least once,
navigate to the environments page under **Operations > Environments**.
Deploy Boards are visible by default. You can explicitly click
the triangle next to their respective environment name in order to hide them.
GitLab will then query Kubernetes for the state of each pod (e.g., waiting,
deploying, finished, unknown), and the Deploy Board status will finally appear.
GitLab will only display a Deploy Board for top-level environments. Foldered
environments like `review/*` (usually used for [Review Apps]) won't have a
Deploy Board attached to them.
## Canary Deployments
A popular CI strategy, where a small portion of the fleet is updated to the new
version of your application.
[Read more about Canary Deployments.](
## Further reading
- [GitLab Autodeploy][autodeploy]
- [GitLab CI environment variables][variables]
- [Environments and deployments][environment]
- [Kubernetes deploy example][kube-deploy]
[ee-1589]: "Deploy Boards initial issue"
[ee]: "GitLab Enterprise Edition landing page"
[kube-deploy]: "Kubernetes deploy example project"
[kubernetes]: "Kubernetes website"
[environment]: ../../ci/ "Environments and deployments documentation"
[docker-exec]: "GitLab Runner Docker executor"
[kube-exec]: "GitLab Runner Kubernetes executor"
[kube-service]: integrations/ "Kubernetes project service"
[review apps]: ../../ci/review_apps/ "Review Apps documentation"
[variables]: ../../ci/variables/ "GitLab CI variables"
[autodeploy]: ../../ci/autodeploy/ "GitLab Autodeploy"
[kube-image]: "Kubernetes deploy Container Registry"
[runners]: ../../ci/runners/
......@@ -2,8 +2,12 @@
>[Introduced][ce-4981] in GitLab 8.11.
We all know that a properly submitted issue is more likely to be addressed in
a timely manner by the developers of a project.
Description templates allow you to define context-specific templates for issue
and merge request description fields for your project.
and merge request description fields for your project, as well as help filter
out a lot of unnecessary noise from issues.
## Overview
......@@ -18,6 +22,18 @@ Description templates must be written in [Markdown](../ and stored
in your project's repository under a directory named `.gitlab`. Only the
templates of the default branch will be taken into account.
## Use-cases
- Add a template to be used in every issue for a specific project,
giving instructions and guidelines, requiring for information specific to that subject.
For example, if you have a project for tracking new blog posts, you can require the
title, outlines, author name, author social media information, etc.
- Following the previous example, you can make a template for every MR submitted
with a new blog post, requiring information about the post date, frontmatter data,
images guidelines, link to the related issue, reviewer name, etc.
- You can also create issues and merge request templates for different
stages of your workflow, e.g., feature proposal, feature improvement, bug report, etc.
## Creating issue templates
Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/`
......@@ -39,6 +55,32 @@ changes you made after picking the template and return it to its initial status.
![Description templates](img/description_templates.png)
## Setting a default template for issues and merge requests **[STARTER]**
> **Notes:**
> - This feature was introduced before [description templates](#overview) and is
> available in [GitLab Starter][products]. It can be enabled
> in the project's settings.
> - Templates for issues were [introduced][ee-28] in GitLab EE 8.1.
> - Templates for merge requests were [introduced][ee-7478ece] in GitLab EE 6.9.
The visibility of issues and/or merge requests should be set to either "Everyone
with access" or "Only team members" in your project's **Settings** otherwise the
template text areas won't show. This is the default behavior so in most cases
you should be fine.
Go to your project's **Settings** and fill in the "Default description template
for issues" and "Default description template for merge requests" text areas
for issues and merge requests respectively. Since GitLab issues and merge
request support [Markdown](../, you can use special markup like
headings, lists, etc.
![Default description templates](img/description_templates_default_settings.png)
After you add the description, hit **Save changes** for the settings to take
effect. Now, every time a new issue or merge request is created, it will be
pre-filled with the text you entered in the template(s).
## Description template example
We make use of Description Templates for Issues and Merge Requests within the GitLab Community Edition project. Please refer to the [`.gitlab` folder][gitlab-ce-templates] for some examples.
......@@ -93,3 +135,6 @@ Possible fixes
[ee-28]: "Merge Request for adding issues template"
[ee-7478ece]: "Commit that introduced merge requests templates"
# File Locking **[PREMIUM]**
> **Notes:**
> - [Introduced][ee-440] in [GitLab Premium][ee] 8.9.
> - This feature needs to have a license with the "File Lock" option enabled. If
> you are using Premium but you don't see the "Lock" button,
> ask your GitLab administrator.
File Locking helps you avoid merge conflicts and better manage your binary files.
Lock any file or directory, make your changes, and then unlock it so another
member of the team can edit it.
## Overview
Working with multiple people on the same file can be a risk. Conflicts
when merging a non-text file are hard to overcome and will require a lot
of manual work to resolve. With GitLab Premium, File
Locking helps you avoid merge conflicts and better manage your binary
files by preventing everyone, except you, from modifying a specific file
or entire directory.
## Use-cases
The file locking feature is useful in situations when:
- Multiple people are working on the same file and you want to avoid merge
- Your repository contains binary files in which situation there is no easy
way to tell the diff between yours and your colleagues' changes.
- Prevent design assets from being overwritten.
Locked directories are locked recursively, which means that everything that
lies under them is also locked.
## Permissions on file locking
The user that locks a file or directory **is the only one** that can edit and
push their changes back to the repository where the locked objects are located.
Locks can be created by any person who has [push access] to the repository; i.e.,
Developer and higher level, and can be removed solely by their author and any
user with Maintainer permissions and above.
If a file is locked and you are not the author of its locked state, a
pre-receive hook will reject your changes when you try to push. In the
following example, a user who has no permissions on the locked `.gitignore`
file will see the message below:
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
remote: GitLab: The path '.gitignore' is locked by Administrator
! [remote rejected] master -> master (pre-receive hook declined)
error: failed to push some refs to ''
Similarly, when a user that is not the author of the locked state of a file
accepts a merge request, an error message will appear stating that the file
is locked.
![Merge request error message](img/file_lock_merge_request_error_message.png)
## Locking a file or a directory
Locking only works for the default branch you have set in the project's settings
(usually `master`).
To lock a file, navigate to the repository tree under the **Repository > Files** tab,
pick the file you want to lock and hit the "Lock" button.
![Locking file](img/file_lock.png)
To lock an entire directory, look for the "Lock" link next to "History".
![Locking directory](img/file_lock_folders.png)
After you lock a file or directory, it will appear as locked in the repository
![Repository view](img/file_lock_repository_view.png)
## Unlocking a file or a directory
To unlock a file or a directory, follow the same procedure as when you locked
them. For a detailed view of every existing lock, see the next section on
"Viewing and managing existing locks".
## Viewing and managing existing locks
To view or manage every existing lock, navigate to the
**Project > Repository > Locked Files** area. There, you can view all existing
locks and [remove the ones you have permission for](#permissions-on-file-locking).
![Locked Files](img/file_lock_list.png)
[ee-440]: "File Lock"
[push access]: ../../user/
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