+Explore GitLab +
++Discover projects, groups and snippets. Share your projects with others +
++
+Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
+++
The basis of Review Apps is the dynamic environments which allow you to create +a new environment (dynamically) for each one of your branches.
+A Review App can then be visible as a link when you visit the merge request +relevant to the branch. That way, you are able to see live all changes introduced +by the merge request changes. Reviewing anything, from performance to interface +changes, becomes much easier with a live environment and as such, Review Apps +can make a huge impact on your development flow.
+They mostly make sense to be used with web applications, but you can use them +any way you'd like.
+Simply put, a Review App is a mapping of a branch with an environment as there +is a 1:1 relation between them.
+Here's an example of what it looks like when viewing a merge request with a +dynamically set environment.
+ +In the image above you can see that the add-new-line
branch was successfully
+built and deployed under a dynamic environment and can be previewed with an
+also dynamically URL.
The details of the Review Apps implementation depend widely on your real +technology stack and on your deployment process. The simplest case is to +deploy a simple static HTML website, but it will not be that straightforward +when your app is using a database for example. To make a branch be deployed +on a temporary instance and booting up this instance with all required software +and services automatically on the fly is not a trivial task. However, it is +doable, especially if you use Docker, or at least a configuration management +tool like Chef, Puppet, Ansible or Salt.
+To get a better understanding of Review Apps, you must first learn how +environments and deployments work. The following docs will help you grasp that +knowledge:
+environment
syntax as defined in .gitlab-ci.yml
.
+This will be your primary reference when you are finally comfortable with
+how environments work.The configuration of Review apps depends on your technology stack and your +infrastructure. Read the dynamic environments documentation to understand +how to define and create them.
+The creation and destruction of a Review App is defined in .gitlab-ci.yml
+at a job level under the environment
keyword.
Check the environments documentation how to do so.
+The process of adding Review Apps in your workflow would look like:
+.gitlab-ci.yml
that uses the predefined
+predefined CI environment variable ${CI_COMMIT_REF_NAME}
to
+create dynamic environments and restrict it to run only on branches.From there on, you would follow the branched Git flow:
+script
+definition of the dynamic environment job.Check the environments limitations.
+A list of examples used with Review Apps can be found below:
+And below is a soon to be added examples list:
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
++Discover projects, groups and snippets. Share your projects with others +
+A collection of .gitlab-ci.yml
template files is maintained at the GitLab CI/CD YAML project. When you create a new file via the UI,
+GitLab will give you the option to choose one of the templates existent on this project.
+If your favorite programming language or framework are missing we would love your
+help by sending a merge request with a new .gitlab-ci.yml
to this project.
There's also a collection of repositories with example projects for various languages. You can fork an adjust them to your own needs.
+(Starter) Analyze your project's Code Quality.
+(Ultimate) Scan your code for vulnerabilities
+(Ultimate) Scan your dependencies for vulnerabilities
+Scan your Docker images for vulnerabilities
+Scan your app for vulnerabilities with GitLab Dynamic Application Security Testing (DAST).
+Analyze your browser performance with Sitespeed.io.
+See the documentation on GitLab Pages for a complete overview.
+Contributions are very welcome! You can help your favorite programming +language users and GitLab by sending a merge request with a guide for that language. +You may want to apply for the GitLab Community Writers Program +to get paid for writing complete articles for GitLab.
+A repository +is what you use to store your codebase in GitLab and change it with version control. +A repository is part of a project, which has a lot of other features.
+To create a new repository, all you need to do is +create a new project.
+Once you create a new project, you can add new files via UI +(read the section below) or via command line. +To add files from the command line, follow the instructions that will +be presented on the screen when you create a new project, or read +through them in the command line basics +documentation.
+++Important: +For security reasons, when using the command line, we strongly recommend +that you connect with GitLab via SSH.
+
Host your codebase in GitLab repositories by pushing your files to GitLab. +You can either use the user interface (UI), or connect your local computer +with GitLab through the command line.
+To configure GitLab CI/CD to build, test, and deploy
+you code, add a file called .gitlab-ci.yml
+to your repository's root.
From the user interface:
+GitLab's UI allows you to perform lots of Git commands without having to +touch the command line. Even if you use the command line regularly, sometimes +it's easier to do so via GitLab UI:
+ +From the command line:
+To get started with the command line, please read through the +command line basics documentation.
+Use GitLab's file finder to search for files in a repository.
+++Introduced in GitLab 9.1
+
Jupyter Notebook (previously IPython Notebook) files are used for +interactive computing in many fields and contain a complete record of the +user's sessions and include code, narrative text, equations and rich output.
+When added to a repository, Jupyter Notebooks with a .ipynb
extension will be
+rendered to HTML when viewed.
Interactive features, including JavaScript plots, will not work when viewed in +GitLab.
+When you submit changes in a new branch, you create a new version +of that project's file tree. Your branch contains all the changes +you are presenting, which are detected by Git line by line.
+To continue your workflow, once you pushed your changes to a new branch, +you can create a merge request, perform +inline code review, and discuss +your implementation with your team. +You can live preview changes submitted to a new branch with +Review Apps.
+With GitLab Starter, you can also request +approval from your managers.
+To create, delete, and branches via GitLab's UI:
+ +Alternatively, you can use the +command line.
+To learn more about branching strategies read through the +GitLab Flow documentation.
+When you commit your changes, +you are introducing those changes to your branch. +Via command line, you can commit multiple times before pushing.
+[ci skip]
+and GitLab CI will skip that pipeline.On GitLab.com, your repository size limit is 10GB +(including LFS). For other instances, the repository size is limited by your +system administrators.
+You can also reduce a repository size using Git.
+All the contributors to your codebase are displayed under your project's Settings > Contributors.
+They are ordered from the collaborator with the greatest number +of commits to the fewest, and displayed on a nice graph:
+ +The repository graph displays visually the Git flow strategy used in that repository:
+ +Find it under your project's Repository > Graph.
+Select branches to compare and view the changes inline:
+ +Find it under your project's Repository > Compare.
+++Available in GitLab Premium.
+
Lock your files to prevent any conflicting changes.
+File Locking is available only in +GitLab Premium.
+You can access your repos via repository API.
+++Introduced in GitLab 11.0
+
Projects that contain a .xcodeproj
or .xcworkspace
directory can now be cloned
+in Xcode using the new Open in Xcode button, located next to the Git URL
+used for cloning your project. The button is only shown on macOS.
++Introduced in GitLab 8.5.
+
When you log into GitLab, you normally want to see where you should spend your +time and take some action, or what you need to keep an eye on. All without the +mess of a huge pile of e-mail notifications. GitLab is where you do your work, +so being able to get started quickly is very important.
+Todos is a chronological list of to-dos that are waiting for your input, all +in a simple dashboard.
+ +You can quickly access the Todos dashboard using the bell icon next to the +search bar in the upper right corner. The number in blue is the number of Todos +you still have open if the count is < 100, else it's 99+. The exact number +will still be shown in the body of the To do tab.
+ +A Todo appears in your Todos dashboard when:
+@mentioned
in an issue or merge request, be it the description of
+the issue/merge request or in a comment,@mentioned
in a comment on a commit,++Introduced in GitLab 9.0.
+
If you are mentioned at the start of a line, the todo you receive will be listed +as 'directly addressed'. For instance, in this comment:
+@alice What do you think? cc: @bob
+
+- @carol can you please have a look?
+
+>>>
+@dan what do you think?
+>>>
+
+@erin @frank thank you!
+The people receiving directly addressed todos are @alice
, @erin
, and
+@frank
. Directly addressed todos only differ from mention todos in their type,
+for filtering; otherwise, they appear as normal.
You can also add an issue or merge request to your Todos dashboard by clicking +the "Add todo" button in the issue or merge request sidebar.
+ +Any action to the corresponding issue or merge request will mark your Todo as +Done. Actions that dismiss Todos include:
+Todos are personal, and they're only marked as done if the action is coming from +you. If you close the issue or merge request, your Todo will automatically +be marked as done.
+If someone else closes, merges, or takes action on the issue or merge +request, your Todo will remain pending. This prevents other users from closing issues without you being notified.
+There is just one Todo per issue or merge request, so mentioning a user a +hundred times in an issue will only trigger one Todo.
+If no action is needed, you can manually mark the Todo as done by clicking the +corresponding Done button, and it will disappear from your Todo list.
+ +A Todo can also be marked as done from the issue or merge request sidebar using +the "Mark todo as done" button.
+ +You can mark all your Todos as done at once by clicking on the Mark all as +done button.
+There are four kinds of filters you can use on your Todos dashboard.
+Filter | +Description | +
---|---|
Project | +Filter by project | +
Author | +Filter by the author that triggered the Todo | +
Type | +Filter by issue or merge request | +
Action | +Filter by the action that triggered the Todo | +
You can also filter by more than one of these at the same time. The possible Actions are Any Action
, Assigned
, Mentioned
, Added
, Pipelines
, and Directly Addressed
, as described above.
++Introduced in GitLab 9.0
+
GitLab offers automatic detection of select Prometheus exporters. Currently supported exporters are:
+ +We have tried to surface the most important metrics for each exporter, and will be continuing to add support for additional exporters in future releases. If you would like to add support for other official exporters, contributions are welcome.
+GitLab retrieves performance data from the configured Prometheus server, and attempts to identifying the presence of known metrics. Once identified, GitLab then needs to be able to map the data to a particular environment.
+In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, +GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the $CI_ENVIRONMENT_SLUG, but may also include other information such as the project's Kubernetes namespace. Each search query is defined in the exporter specific documentation.
+We strive to support the 2-4 most important metrics for each common system service that supports Prometheus. If you are looking for support for a particular exporter which has not yet been added to the library, additions can be made to the additional_metrics.yml
file.
++Note: The library is only for monitoring public, common, system services which all customers can benefit from. Support for monitoring customer proprietary metrics will be added in a subsequent release.
+
+Discover projects, groups and snippets. Share your projects with others +
+++Introduced in GitLab 8.7.
+
GitLab implements Git's powerful feature to cherry-pick any commit +with introducing a Cherry-pick button in merge requests and commit details.
+After the merge request has been merged, a Cherry-pick button will be available +to cherry-pick the changes introduced by that merge request.
+ +After you click that button, a modal will appear where you can choose to +cherry-pick the changes directly into the selected branch or you can opt to +create a new merge request with the cherry-pick changes
+You can cherry-pick a Commit from the Commit details page:
+ +Similar to cherry-picking a merge request, you can opt to cherry-pick the changes +directly into the target branch or create a new merge request to cherry-pick the +changes.
+Please note that when cherry-picking merge commits, the mainline will always be the +first parent. If you want to use a different mainline then you need to do that +from the command line.
+Here is a quick example to cherry-pick a merge commit using the second parent as the +mainline:
+git cherry-pick -m 2 7a39eb0
++Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+Git is a distributed version control system, which means you can work locally +but you can also share or "push" your changes to other servers. +Before you can push your changes to a GitLab server +you need a secure communication channel for sharing information.
+The SSH protocol provides this security and allows you to authenticate to the +GitLab remote server without supplying your username or password each time.
+For a more detailed explanation of how the SSH protocol works, we advise you to +read this nice tutorial by DigitalOcean.
+Before generating a new SSH key pair check if your system already has one +at the default location by opening a shell, or Command Prompt on Windows, +and running the following command:
+Windows Command Prompt:
+type %userprofile%\.ssh\id_rsa.pub
+Git Bash on Windows / GNU/Linux / macOS / PowerShell:
+cat ~/.ssh/id_rsa.pub
+If you see a string starting with ssh-rsa
you already have an SSH key pair
+and you can skip the generate portion of the next section and skip to the copy
+to clipboard step.
+If you don't see the string or would like to generate a SSH key pair with a
+custom name continue onto the next step.
Note that Public SSH key may also be named as follows:
+id_dsa.pub
id_ecdsa.pub
id_ed25519.pub
To generate a new SSH key pair, use the following command:
+Git Bash on Windows / GNU/Linux / macOS:
+ssh-keygen -t rsa -C "your.email@example.com" -b 4096
+Windows:
+Alternatively on Windows you can download +PuttyGen +and follow this documentation article to generate a SSH key pair.
+Next, you will be prompted to input a file path to save your SSH key pair to.
+If you don't already have an SSH key pair use the suggested path by pressing +enter. Using the suggested path will normally allow your SSH client +to automatically use the SSH key pair with no additional configuration.
+If you already have a SSH key pair with the suggested file path, you will need
+to input a new file path and declare what host this SSH key pair will be used
+for in your .ssh/config
file, see Working with non-default SSH key pair paths
+for more information.
Once you have input a file path you will be prompted to input a password to +secure your SSH key pair. It is a best practice to use a password for an SSH +key pair, but it is not required and you can skip creating a password by +pressing enter.
+NOTE: Note:
+If you want to change the password of your SSH key pair, you can use
+ssh-keygen -p <keyname>
.
The next step is to copy the public SSH key as we will need it afterwards.
+To copy your public SSH key to the clipboard, use the appropriate code below:
+macOS:
+pbcopy < ~/.ssh/id_rsa.pub
+GNU/Linux (requires the xclip package):
+xclip -sel clip < ~/.ssh/id_rsa.pub
+Windows Command Line:
+type %userprofile%\.ssh\id_rsa.pub | clip
+Git Bash on Windows / Windows PowerShell:
+cat ~/.ssh/id_rsa.pub | clip
+The final step is to add your public SSH key to GitLab.
+Navigate to the 'SSH Keys' tab in your 'Profile Settings'. +Paste your key in the 'Key' section and give it a relevant 'Title'. +Use an identifiable title like 'Work Laptop - Windows 7' or +'Home MacBook Pro 15'.
+If you manually copied your public SSH key make sure you copied the entire
+key starting with ssh-rsa
and ending with your email.
Optionally you can test your setup by running ssh -T git@example.com
+(replacing example.com
with your GitLab domain) and verifying that you
+receive a Welcome to GitLab
message.
If you used a non-default file path for your GitLab SSH key pair,
+you must configure your SSH client to find your GitLab private SSH key
+for connections to your GitLab server (perhaps gitlab.com
).
For your current terminal session you can do so using the following commands
+(replacing other_id_rsa
with your private SSH key):
Git Bash on Windows / GNU/Linux / macOS:
+eval $(ssh-agent -s)
+ssh-add ~/.ssh/other_id_rsa
+To retain these settings you'll need to save them to a configuration file.
+For OpenSSH clients this is configured in the ~/.ssh/config
file for some
+operating systems.
+Below are two example host configurations using their own SSH key:
# GitLab.com server
+Host gitlab.com
+RSAAuthentication yes
+IdentityFile ~/.ssh/config/private-key-filename-01
+
+# Private GitLab server
+Host gitlab.company.com
+RSAAuthentication yes
+IdentityFile ~/.ssh/config/private-key-filename
+Due to the wide variety of SSH clients and their very large number of +configuration options, further explanation of these topics is beyond the scope +of this document.
+Public SSH keys need to be unique, as they will bind to your account. +Your SSH key is the only identifier you'll have when pushing code via SSH. +That's why it needs to uniquely map to a single user.
+Deploy keys allow read-only or read-write (if enabled) access to one or +multiple projects with a single SSH key pair.
+This is really useful for cloning repositories to your Continuous +Integration (CI) server. By using deploy keys, you don't have to set up a +dummy user account.
+If you are a project maintainer or owner, you can add a deploy key in the +project settings under the section 'Repository'. Specify a title for the new +deploy key and paste a public SSH key. After this, the machine that uses +the corresponding private SSH key has read-only or read-write (if enabled) +access to the project.
+You can't add the same deploy key twice using the form. +If you want to add the same key to another project, please enable it in the +list that says 'Deploy keys from projects available to you'. All the deploy +keys of all the projects you have access to are available. This project +access can happen through being a direct member of the project, or through +a group.
+Deploy keys can be shared between projects, you just need to add them to each +project.
+Global Shared Deploy keys allow read-only or read-write (if enabled) access to +be configured on any repository in the entire GitLab installation.
+This is really useful for integrating repositories to secured, shared Continuous +Integration (CI) services or other shared services. +GitLab administrators can set up the Global Shared Deploy key in GitLab and +add the private key to any shared systems. Individual repositories opt into +exposing their repository using these keys when a project maintainers (or higher) +authorizes a Global Shared Deploy key to be used with their project.
+Global Shared Keys can provide greater security compared to Per-Project Deploy +Keys since an administrator of the target integrated system is the only one +who needs to know and configure the private key.
+GitLab administrators set up Global Deploy keys in the Admin area under the +section Deploy Keys. Ensure keys have a meaningful title as that will be +the primary way for project maintainers and owners to identify the correct Global +Deploy key to add. For instance, if the key gives access to a SaaS CI instance, +use the name of that service in the key name if that is all it is used for. +When creating Global Shared Deploy keys, give some thought to the granularity +of keys - they could be of very narrow usage such as just a specific service or +of broader usage for something like "Anywhere you need to give read access to +your repository".
+Once a GitLab administrator adds the Global Deployment key, project maintainers +and owners can add it in project's Settings > Repository section by expanding the +Deploy Key section and clicking Enable next to the appropriate key listed +under Public deploy keys available to any project.
+NOTE: Note: +The heading Public deploy keys available to any project only appears +if there is at least one Global Deploy Key configured.
+CAUTION: Warning: +Defining Global Deploy Keys does not expose any given repository via +the key until that repository adds the Global Deploy Key to their project. +In this way the Global Deploy Keys enable access by other systems, but do +not implicitly give any access just by setting them up.
+How to add your SSH key to Eclipse: https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration
+GitLab integrates with the system-installed SSH daemon, designating a user
+(typically named git
) through which all access requests are handled. Users
+connecting to the GitLab server over SSH are identified by their SSH key instead
+of their username.
SSH client operations performed on the GitLab server wil be executed as this +user. Although it is possible to modify the SSH configuration for this user to, +e.g., provide a private SSH key to authenticate these requests by, this practice +is not supported and is strongly discouraged as it presents significant +security risks.
+The GitLab check process includes a check for this condition, and will direct you +to this section if your server is configured like this, e.g.:
+$ gitlab-rake gitlab:check
+# ...
+Git user has default SSH configuration? ... no
+ Try fixing it:
+ mkdir ~/gitlab-check-backup-1504540051
+ sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051
+ sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051
+ For more information see:
+ doc/ssh/README.md in section "SSH on the GitLab server"
+ Please fix the error above and rerun the checks.
+Remove the custom configuration as soon as you're able to. These customizations +are explicitly not supported and may stop working at any time.
+If on Git clone you are prompted for a password like git@gitlab.com's password:
+something is wrong with your SSH setup.
ssh-agent
as documented
+earlier in this documentssh -Tv git@example.com
+(replacing example.com
with your GitLab domain)+Discover projects, groups and snippets. Share your projects with others +
+This document describes the usage of .gitlab-ci.yml
, the file that is used by
+GitLab Runner to manage your project's jobs.
From version 7.12, GitLab CI uses a YAML
+file (.gitlab-ci.yml
) for the project configuration. It is placed in the root
+of your repository and contains definitions of how your project should be built.
If you want a quick introduction to GitLab CI, follow our +quick start guide.
+NOTE: Note: +If you have a mirrored repository where GitLab pulls from, +you may need to enable pipeline triggering in your project's +Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates.
+The YAML file defines a set of jobs with constraints stating when they should
+be run. You can specify an unlimited number of jobs which are defined as
+top-level elements with an arbitrary name and always have to contain at least
+the script
clause.
job1:
+ script: "execute-script-for-job1"
+
+job2:
+ script: "execute-script-for-job2"
+The above example is the simplest possible CI/CD configuration with two separate
+jobs, where each of the jobs executes a different command.
+Of course a command can execute code directly (./configure;make;make install
)
+or run a script (test.sh
) in the repository.
Jobs are picked up by Runners and executed within the +environment of the Runner. What is important, is that each job is run +independently from each other.
+Each job must have a unique name, but there are a few reserved keywords
that
+cannot be used as job names:
image
services
stages
types
before_script
after_script
variables
cache
A job is defined by a list of parameters that define the job behavior.
+Keyword | +Required | +Description | +
---|---|---|
script | +yes | +Defines a shell script which is executed by Runner | +
image | +no | +Use docker image, covered in Using Docker Images + | +
services | +no | +Use docker services, covered in Using Docker Images + | +
stage | +no | +Defines a job stage (default: test ) |
+
type | +no | +Alias for stage
+ |
+
variables | +no | +Define job variables on a job level | +
only | +no | +Defines a list of git refs for which job is created | +
except | +no | +Defines a list of git refs for which job is not created | +
tags | +no | +Defines a list of tags which are used to select Runner | +
allow_failure | +no | +Allow job to fail. Failed job doesn't contribute to commit status | +
when | +no | +Define when to run job. Can be on_success , on_failure , always or manual
+ |
+
dependencies | +no | +Define other jobs that a job depends on so that you can pass artifacts between them | +
artifacts | +no | +Define list of job artifacts + | +
cache | +no | +Define list of files that should be cached between subsequent runs | +
before_script | +no | +Override a set of commands that are executed before job | +
after_script | +no | +Override a set of commands that are executed after job | +
environment | +no | +Defines a name of environment to which deployment is done by this job | +
coverage | +no | +Define code coverage settings for a given job | +
retry | +no | +Define how many times a job can be auto-retried in case of a failure | +
pages
+pages
is a special job that is used to upload static content to GitLab that
+can be used to serve your website. It has a special syntax, so the two
+requirements below must be met:
public/
directoryartifacts
with a path to the public/
directory must be definedThe example below simply moves all files from the root of the project to the
+public/
directory. The .public
workaround is so cp
doesn't also copy
+public/
to itself in an infinite loop:
pages:
+ stage: deploy
+ script:
+ - mkdir .public
+ - cp -r * .public
+ - mv .public public
+ artifacts:
+ paths:
+ - public
+ only:
+ - master
+Read more on GitLab Pages user documentation.
+image
and services
+This allows to specify a custom Docker image and a list of services that can be +used for time of the job. The configuration of this feature is covered in +a separate document.
+before_script
and after_script
+++Introduced in GitLab 8.7 and requires Gitlab Runner v1.2
+
before_script
is used to define the command that should be run before all
+jobs, including deploy jobs, but after the restoration of artifacts.
+This can be an array or a multi-line string.
after_script
is used to define the command that will be run after for all
+jobs, including failed ones. This has to be an array or a multi-line string.
The before_script
and the main script
are concatenated and run in a single context/container.
+The after_script
is run separately, so depending on the executor, changes done
+outside of the working tree might not be visible, e.g. software installed in the
+before_script
.
It's possible to overwrite the globally defined before_script
and after_script
+if you set it per-job:
before_script:
+ - global before script
+
+job:
+ before_script:
+ - execute this instead of global before script
+ script:
+ - my command
+ after_script:
+ - execute this after my script
+stages
+stages
is used to define stages that can be used by jobs and is defined
+globally.
The specification of stages
allows for having flexible multi stage pipelines.
+The ordering of elements in stages
defines the ordering of jobs' execution:
Let's consider the following example, which defines 3 stages:
+stages:
+ - build
+ - test
+ - deploy
+build
are executed in parallel.build
succeed, the test
jobs are executed in parallel.test
succeed, the deploy
jobs are executed in parallel.deploy
succeed, the commit is marked as passed
.failed
and no
+jobs of further stage are executed.There are also two edge cases worth mentioning:
+stages
are defined in .gitlab-ci.yml
, then the build
,
+test
and deploy
are allowed to be used as job's stage by default.stage
, the job is assigned the test
stage.stage
+stage
is defined per-job and relies on stages
which is defined
+globally. It allows to group jobs into different stages, and jobs of the same
+stage
are executed in parallel
. For example:
stages:
+ - build
+ - test
+ - deploy
+
+job 1:
+ stage: build
+ script: make build dependencies
+
+job 2:
+ stage: build
+ script: make build artifacts
+
+job 3:
+ stage: test
+ script: make test
+
+job 4:
+ stage: deploy
+ script: make deploy
+types
+CAUTION: Deprecated:
+types
is deprecated, and could be removed in one of the future releases.
+Use stages instead.
script
+script
is the only required keyword that a job needs. It's a shell script
+which is executed by the Runner. For example:
job:
+ script: "bundle exec rspec"
+This parameter can also contain several commands using an array:
+job:
+ script:
+ - uname -a
+ - bundle exec rspec
+Sometimes, script
commands will need to be wrapped in single or double quotes.
+For example, commands that contain a colon (:
) need to be wrapped in quotes so
+that the YAML parser knows to interpret the whole thing as a string rather than
+a "key: value" pair. Be careful when using special characters:
+:
, {
, }
, [
, ]
, ,
, &
, *
, #
, ?
, |
, -
, <
, >
, =
, !
, %
, @
, `
.
only
and except
(simplified)only
and except
are two parameters that set a job policy to limit when
+jobs are created:
only
defines the names of branches and tags for which the job will run.except
defines the names of branches and tags for which the job will
+not run.There are a few rules that apply to the usage of job policy:
+only
and except
are inclusive. If both only
and except
are defined
+in a job specification, the ref is filtered by only
and except
.only
and except
allow the use of regular expressions.only
and except
allow to specify a repository path to filter jobs for
+forks.In addition, only
and except
allow the use of special keywords:
Value | +Description | +
---|---|
branches |
+When a branch is pushed. | +
tags |
+When a tag is pushed. | +
api |
+When pipeline has been triggered by a second pipelines API (not triggers API). | +
external |
+When using CI services other than GitLab. | +
pipelines |
+For multi-project triggers, created using the API with CI_JOB_TOKEN . |
+
pushes |
+Pipeline is triggered by a git push by the user. |
+
schedules |
+For scheduled pipelines. | +
triggers |
+For pipelines created using a trigger token. | +
web |
+For pipelines created using Run pipeline button in GitLab UI (under your project's Pipelines). | +
In the example below, job
will run only for refs that start with issue-
,
+whereas all branches will be skipped:
job:
+ # use regexp
+ only:
+ - /^issue-.*$/
+ # use special keyword
+ except:
+ - branches
+In this example, job
will run only for refs that are tagged, or if a build is
+explicitly requested via an API trigger or a Pipeline Schedule:
job:
+ # use special keywords
+ only:
+ - tags
+ - triggers
+ - schedules
+The repository path can be used to have jobs executed only for the parent +repository and not forks:
+job:
+ only:
+ - branches@gitlab-org/gitlab-ce
+ except:
+ - master@gitlab-org/gitlab-ce
+The above example will run job
for all branches on gitlab-org/gitlab-ce
,
+except master.
only
and except
(complex)+++
refs
andkubernetes
policies introduced in GitLab 10.0
+++
variables
policy introduced in 10.7
CAUTION: Warning: +This an alpha feature, and it it subject to change at any time without +prior notice!
+Since GitLab 10.0 it is possible to define a more elaborate only/except job +policy configuration.
+GitLab now supports both, simple and complex strategies, so it is possible to +use an array and a hash configuration scheme.
+Three keys are now available: refs
, kubernetes
and variables
.
+Refs strategy equals to simplified only/except configuration, whereas
+kubernetes strategy accepts only active
keyword.
variables
keyword is used to define variables expressions. In other words
+you can use predefined variables / project / group or
+environment-scoped variables to define an expression GitLab is going to
+evaluate in order to decide whether a job should be created or not.
See the example below. Job is going to be created only when pipeline has been
+scheduled or runs for a master
branch, and only if kubernetes service is
+active in the project.
job:
+ only:
+ refs:
+ - master
+ - schedules
+ kubernetes: active
+Examples of using variables expressions:
+deploy:
+ script: cap staging deploy
+ only:
+ refs:
+ - branches
+ variables:
+ - $RELEASE == "staging"
+ - $STAGING
+Another use case is exluding jobs depending on a commit message (added in 11.0):
+end-to-end:
+ script: rake test:end-to-end
+ except:
+ variables:
+ - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/
+Learn more about variables expressions on a separate page.
+tags
+tags
is used to select specific Runners from the list of all Runners that are
+allowed to run this project.
During the registration of a Runner, you can specify the Runner's tags, for
+example ruby
, postgres
, development
.
tags
allow you to run jobs with Runners that have the specified tags
+assigned to them:
job:
+ tags:
+ - ruby
+ - postgres
+The specification above, will make sure that job
is built by a Runner that
+has both ruby
AND postgres
tags defined.
allow_failure
+allow_failure
is used when you want to allow a job to fail without impacting
+the rest of the CI suite. Failed jobs don't contribute to the commit status.
When enabled and the job fails, the pipeline will be successful/green for all +intents and purposes, but a "CI build passed with warnings" message will be +displayed on the merge request or commit or job page. This is to be used by +jobs that are allowed to fail, but where failure indicates some other (manual) +steps should be taken elsewhere.
+In the example below, job1
and job2
will run in parallel, but if job1
+fails, it will not stop the next stage from running, since it's marked with
+allow_failure: true
:
job1:
+ stage: test
+ script:
+ - execute_script_that_will_fail
+ allow_failure: true
+
+job2:
+ stage: test
+ script:
+ - execute_script_that_will_succeed
+
+job3:
+ stage: deploy
+ script:
+ - deploy_to_staging
+when
+when
is used to implement jobs that are run in case of failure or despite the
+failure.
when
can be set to one of the following values:
on_success
- execute job only when all jobs from prior stages
+succeed. This is the default.on_failure
- execute job only when at least one job from prior stages
+fails.always
- execute job regardless of the status of jobs from prior stages.manual
- execute job manually (added in GitLab 8.10). Read about
+manual actions below.For example:
+stages:
+ - build
+ - cleanup_build
+ - test
+ - deploy
+ - cleanup
+
+build_job:
+ stage: build
+ script:
+ - make build
+
+cleanup_build_job:
+ stage: cleanup_build
+ script:
+ - cleanup build when failed
+ when: on_failure
+
+test_job:
+ stage: test
+ script:
+ - make test
+
+deploy_job:
+ stage: deploy
+ script:
+ - make deploy
+ when: manual
+
+cleanup_job:
+ stage: cleanup
+ script:
+ - cleanup after jobs
+ when: always
+The above script will:
+cleanup_build_job
only when build_job
fails.cleanup_job
as the last step in pipeline regardless of
+success or failure.deploy_job
from GitLab's UI.when:manual
+++Notes:
+
Manual actions are a special type of job that are not executed automatically, +they need to be explicitly started by a user. An example usage of manual actions +would be a deployment to a production environment. Manual actions can be started +from the pipeline, job, environment, and deployment views. Read more at the +environments documentation.
+Manual actions can be either optional or blocking. Blocking manual actions will +block the execution of the pipeline at the stage this action is defined in. It's +possible to resume execution of the pipeline when someone executes a blocking +manual action by clicking a play button.
+When a pipeline is blocked, it will not be merged if Merge When Pipeline Succeeds
+is set. Blocked pipelines also do have a special status, called manual.
+Manual actions are non-blocking by default. If you want to make manual action
+blocking, it is necessary to add allow_failure: false
to the job's definition
+in .gitlab-ci.yml
.
Optional manual actions have allow_failure: true
set by default and their
+Statuses do not contribute to the overall pipeline status. So, if a manual
+action fails, the pipeline will eventually succeed.
Manual actions are considered to be write actions, so permissions for +protected branches are used when +user wants to trigger an action. In other words, in order to trigger a manual +action assigned to a branch that the pipeline is running for, user needs to +have ability to merge to this branch.
+environment
+++
Notes:
+environment
is used to define that a job deploys to a specific environment.
+If environment
is specified and no environment under that name exists, a new
+one will be created automatically.
In its simplest form, the environment
keyword can be defined like:
deploy to production:
+ stage: deploy
+ script: git push production HEAD:master
+ environment:
+ name: production
+In the above example, the deploy to production
job will be marked as doing a
+deployment to the production
environment.
environment:name
+++
Notes:
+environment: production
. The recommended way now is to define it under the
+name
keyword.name
parameter can use any of the defined CI variables,
+including predefined, secure variables and .gitlab-ci.yml
variables
.
+You however cannot use variables defined under script
.The environment
name can contain:
-
_
/
$
{
}
Common names are qa
, staging
, and production
, but you can use whatever
+name works with your workflow.
Instead of defining the name of the environment right after the environment
+keyword, it is also possible to define it as a separate value. For that, use
+the name
keyword under environment
:
deploy to production:
+ stage: deploy
+ script: git push production HEAD:master
+ environment:
+ name: production
+environment:url
+++
Notes:
+.gitlab-ci.yml
.url
parameter can use any of the defined CI variables,
+including predefined, secure variables and .gitlab-ci.yml
variables
.
+You however cannot use variables defined under script
.This is an optional value that when set, it exposes buttons in various places +in GitLab which when clicked take you to the defined URL.
+In the example below, if the job finishes successfully, it will create buttons
+in the merge requests and in the environments/deployments pages which will point
+to https://prod.example.com
.
deploy to production:
+ stage: deploy
+ script: git push production HEAD:master
+ environment:
+ name: production
+ url: https://prod.example.com
+environment:on_stop
+++
Notes:
+Closing (stoping) environments can be achieved with the on_stop
keyword defined under
+environment
. It declares a different job that runs in order to close
+the environment.
Read the environment:action
section for an example.
environment:action
+++Introduced in GitLab 8.13.
+
The action
keyword is to be used in conjunction with on_stop
and is defined
+in the job that is called to close the environment.
Take for instance:
+review_app:
+ stage: deploy
+ script: make deploy-app
+ environment:
+ name: review
+ on_stop: stop_review_app
+
+stop_review_app:
+ stage: deploy
+ script: make delete-app
+ when: manual
+ environment:
+ name: review
+ action: stop
+In the above example we set up the review_app
job to deploy to the review
+environment, and we also defined a new stop_review_app
job under on_stop
.
+Once the review_app
job is successfully finished, it will trigger the
+stop_review_app
job based on what is defined under when
. In this case we
+set it up to manual
so it will need a manual action via
+GitLab's web interface in order to run.
The stop_review_app
job is required to have the following keywords defined:
when
- reference
+environment:name
environment:action
stage
should be the same as the review_app
in order for the environment
+to stop automatically when the branch is deleted++
Notes:
+$CI_ENVIRONMENT_SLUG
was introduced in GitLab 8.15.name
and url
parameters can use any of the defined CI variables,
+including predefined, secure variables and .gitlab-ci.yml
variables
.
+You however cannot use variables defined under script
.For example:
+deploy as review app:
+ stage: deploy
+ script: make deploy
+ environment:
+ name: review/$CI_COMMIT_REF_NAME
+ url: https://$CI_ENVIRONMENT_SLUG.example.com/
+The deploy as review app
job will be marked as deployment to dynamically
+create the review/$CI_COMMIT_REF_NAME
environment, where $CI_COMMIT_REF_NAME
+is an environment variable set by the Runner. The
+$CI_ENVIRONMENT_SLUG
variable is based on the environment name, but suitable
+for inclusion in URLs. In this case, if the deploy as review app
job was run
+in a branch named pow
, this environment would be accessible with an URL like
+https://review-pow.example.com/
.
This of course implies that the underlying server which hosts the application +is properly configured.
+The common use case is to create dynamic environments for branches and use them +as Review Apps. You can see a simple example using Review Apps at +https://gitlab.com/gitlab-examples/review-apps-nginx/.
+cache
+++
Notes:
+cache
can be set globally and per-job.TIP: Learn more: +Read how caching works and find out some good practices in the +caching dependencies documentation.
+cache
is used to specify a list of files and directories which should be
+cached between jobs. You can only use paths that are within the project
+workspace.
If cache
is defined outside the scope of jobs, it means it is set
+globally and all jobs will use that definition.
cache:paths
+Use the paths
directive to choose which files or directories will be cached.
+Wildcards can be used as well.
Cache all files in binaries
that end in .apk
and the .config
file:
rspec:
+ script: test
+ cache:
+ paths:
+ - binaries/*.apk
+ - .config
+Locally defined cache overrides globally defined options. The following rspec
+job will cache only binaries/
:
cache:
+ paths:
+ - my/files
+
+rspec:
+ script: test
+ cache:
+ key: rspec
+ paths:
+ - binaries/
+Note that since cache is shared between jobs, if you're using different +paths for different jobs, you should also set a different cache:key +otherwise cache content can be overwritten.
+cache:key
+++Introduced in GitLab Runner v1.0.0.
+
Since the cache is shared between jobs, if you're using different
+paths for different jobs, you should also set a different cache:key
+otherwise cache content can be overwritten.
The key
directive allows you to define the affinity of caching between jobs,
+allowing to have a single cache for all jobs, cache per-job, cache per-branch
+or any other way that fits your workflow. This way, you can fine tune caching,
+allowing you to cache data between different jobs or even different branches.
The cache:key
variable can use any of the
+predefined variables, and the default key, if not
+set, is just literal default
which means everything is shared between each
+pipelines and jobs by default, starting from GitLab 9.0.
NOTE: Note:
+The cache:key
variable cannot contain the /
character, or the equivalent
+URI-encoded %2F
; a value made only of dots (.
, %2E
) is also forbidden.
For example, to enable per-branch caching:
+cache:
+ key: "$CI_COMMIT_REF_SLUG"
+ paths:
+ - binaries/
+If you use Windows Batch to run your shell scripts you need to replace
+$
with %
:
cache:
+ key: "%CI_COMMIT_REF_SLUG%"
+ paths:
+ - binaries/
+cache:untracked
+Set untracked: true
to cache all files that are untracked in your Git
+repository:
rspec:
+ script: test
+ cache:
+ untracked: true
+Cache all Git untracked files and files in binaries
:
rspec:
+ script: test
+ cache:
+ untracked: true
+ paths:
+ - binaries/
+cache:policy
+++Introduced in GitLab 9.4.
+
The default behaviour of a caching job is to download the files at the start of
+execution, and to re-upload them at the end. This allows any changes made by the
+job to be persisted for future runs, and is known as the pull-push
cache
+policy.
If you know the job doesn't alter the cached files, you can skip the upload step
+by setting policy: pull
in the job specification. Typically, this would be
+twinned with an ordinary cache job at an earlier stage to ensure the cache
+is updated from time to time:
stages:
+ - setup
+ - test
+
+prepare:
+ stage: setup
+ cache:
+ key: gems
+ paths:
+ - vendor/bundle
+ script:
+ - bundle install --deployment
+
+rspec:
+ stage: test
+ cache:
+ key: gems
+ paths:
+ - vendor/bundle
+ policy: pull
+ script:
+ - bundle exec rspec ...
+This helps to speed up job execution and reduce load on the cache server, +especially when you have a large number of cache-using jobs executing in +parallel.
+Additionally, if you have a job that unconditionally recreates the cache without
+reference to its previous contents, you can use policy: push
in that job to
+skip the download step.
artifacts
+++
Notes:
+artifacts
is used to specify a list of files and directories which should be
+attached to the job after success.
The artifacts will be sent to GitLab after the job finishes successfully and will +be available for download in the GitLab UI.
+ +artifacts:paths
+You can only use paths that are within the project workspace. To pass artifacts +between different jobs, see dependencies.
+Send all files in binaries
and .config
:
artifacts:
+ paths:
+ - binaries/
+ - .config
+To disable artifact passing, define the job with empty dependencies:
+job:
+ stage: build
+ script: make build
+ dependencies: []
+You may want to create artifacts only for tagged releases to avoid filling the +build server storage with temporary build artifacts.
+Create artifacts only for tags (default-job
will not create artifacts):
default-job:
+ script:
+ - mvn test -U
+ except:
+ - tags
+
+release-job:
+ script:
+ - mvn package -U
+ artifacts:
+ paths:
+ - target/*.war
+ only:
+ - tags
+artifacts:name
+++Introduced in GitLab 8.6 and GitLab Runner v1.1.0.
+
The name
directive allows you to define the name of the created artifacts
+archive. That way, you can have a unique name for every archive which could be
+useful when you'd like to download the archive from GitLab. The artifacts:name
+variable can make use of any of the predefined variables.
+The default name is artifacts
, which becomes artifacts.zip
when downloaded.
NOTE: Note:
+If your branch-name contains forward slashes
+(e.g. feature/my-feature
) it is advised to use $CI_COMMIT_REF_SLUG
+instead of $CI_COMMIT_REF_NAME
for proper naming of the artifact.
To create an archive with a name of the current job:
+job:
+ artifacts:
+ name: "$CI_JOB_NAME"
+ paths:
+ - binaries/
+To create an archive with a name of the current branch or tag including only +the binaries directory:
+job:
+ artifacts:
+ name: "$CI_COMMIT_REF_NAME"
+ paths:
+ - binaries/
+To create an archive with a name of the current job and the current branch or +tag including only the binaries directory:
+job:
+ artifacts:
+ name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
+ paths:
+ - binaries/
+To create an archive with a name of the current stage and branch name:
+job:
+ artifacts:
+ name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
+ paths:
+ - binaries/
+If you use Windows Batch to run your shell scripts you need to replace
+$
with %
:
job:
+ artifacts:
+ name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
+ paths:
+ - binaries/
+If you use Windows PowerShell to run your shell scripts you need to replace
+$
with $env:
:
job:
+ artifacts:
+ name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
+ paths:
+ - binaries/
+artifacts:untracked
+artifacts:untracked
is used to add all Git untracked files as artifacts (along
+to the paths defined in artifacts:paths
).
NOTE: Note:
+To exclude the folders/files which should not be a part of untracked
just
+add them to .gitignore
.
Send all Git untracked files:
+artifacts:
+ untracked: true
+Send all Git untracked files and files in binaries
:
artifacts:
+ untracked: true
+ paths:
+ - binaries/
+artifacts:when
+++Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
+
artifacts:when
is used to upload artifacts on job failure or despite the
+failure.
artifacts:when
can be set to one of the following values:
on_success
- upload artifacts only when the job succeeds. This is the default.on_failure
- upload artifacts only when the job fails.always
- upload artifacts regardless of the job status.To upload artifacts only when job fails:
+job:
+ artifacts:
+ when: on_failure
+artifacts:expire_in
+++Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
+
expire_in
allows you to specify how long artifacts should live before they
+expire and therefore deleted, counting from the time they are uploaded and
+stored on GitLab. If the expiry time is not defined, it defaults to the
+instance wide setting
+(30 days by default, forever on GitLab.com).
You can use the Keep button on the job page to override expiration and +keep artifacts forever.
+After their expiry, artifacts are deleted hourly by default (via a cron job), +and are not accessible anymore.
+The value of expire_in
is an elapsed time. Examples of parsable values:
To expire artifacts 1 week after being uploaded:
+job:
+ artifacts:
+ expire_in: 1 week
+dependencies
+++Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
+
This feature should be used in conjunction with artifacts
and
+allows you to define the artifacts to pass between different jobs.
Note that artifacts
from all previous stages are passed by default.
To use this feature, define dependencies
in context of the job and pass
+a list of all previous jobs from which the artifacts should be downloaded.
+You can only define jobs from stages that are executed before the current one.
+An error will be shown if you define jobs from the current stage or next ones.
+Defining an empty array will skip downloading any artifacts for that job.
+The status of the previous job is not considered when using dependencies
, so
+if it failed or it is a manual job that was not run, no error occurs.
In the following example, we define two jobs with artifacts, build:osx
and
+build:linux
. When the test:osx
is executed, the artifacts from build:osx
+will be downloaded and extracted in the context of the build. The same happens
+for test:linux
and artifacts from build:linux
.
The job deploy
will download artifacts from all previous jobs because of
+the stage precedence:
build:osx:
+ stage: build
+ script: make build:osx
+ artifacts:
+ paths:
+ - binaries/
+
+build:linux:
+ stage: build
+ script: make build:linux
+ artifacts:
+ paths:
+ - binaries/
+
+test:osx:
+ stage: test
+ script: make test:osx
+ dependencies:
+ - build:osx
+
+test:linux:
+ stage: test
+ script: make test:linux
+ dependencies:
+ - build:linux
+
+deploy:
+ stage: deploy
+ script: make deploy
+++Introduced in GitLab 10.3.
+
If the artifacts of the job that is set as a dependency have been +expired or +erased, then +the dependent job will fail.
+NOTE: Note: +You can ask your administrator to +flip this switch +and bring back the old behavior.
+coverage
+++Introduced in GitLab 8.17.
+
coverage
allows you to configure how code coverage will be extracted from the
+job output.
Regular expressions are the only valid kind of value expected here. So, using
+surrounding /
is mandatory in order to consistently and explicitly represent
+a regular expression string. You must escape special characters if you want to
+match them literally.
A simple example:
+job1:
+ script: rspec
+ coverage: '/Code coverage: \d+\.\d+/'
+retry
+++Introduced in GitLab 9.5.
+
retry
allows you to configure how many times a job is going to be retried in
+case of a failure.
When a job fails, and has retry
configured it is going to be processed again
+up to the amount of times specified by the retry
keyword.
If retry
is set to 2, and a job succeeds in a second run (first retry), it won't be retried
+again. retry
value has to be a positive integer, equal or larger than 0, but
+lower or equal to 2 (two retries maximum, three runs in total).
A simple example:
+test:
+ script: rspec
+ retry: 2
+variables
+++Introduced in GitLab Runner v0.5.0.
+
NOTE: Note: +Integers (as well as strings) are legal both for variable's name and value. +Floats are not legal and cannot be used.
+GitLab CI/CD allows you to define variables inside .gitlab-ci.yml
that are
+then passed in the job environment. They can be set globally and per-job.
+When the variables
keyword is used on a job level, it overrides the global
+YAML variables and predefined ones.
They are stored in the Git repository and are meant to store non-sensitive +project configuration, for example:
+variables:
+ DATABASE_URL: "postgres://postgres@postgres/my_database"
+These variables can be later used in all executed commands and scripts. +The YAML-defined variables are also set to all created service containers, +thus allowing to fine tune them.
+To turn off global defined variables in a specific job, define an empty hash:
+job_name:
+ variables: {}
+Except for the user defined variables, there are also the ones set up by the
+Runner itself.
+One example would be CI_COMMIT_REF_NAME
which has the value of
+the branch or tag name for which project is built. Apart from the variables
+you can set in .gitlab-ci.yml
, there are also the so called
+Variables
+which can be set in GitLab's UI.
Learn more about variables and their priority.
+++Introduced in GitLab 8.9 as an experimental feature. May change or be removed +completely in future releases.
+GIT_STRATEGY=none
requires GitLab Runner +v1.7+.
You can set the GIT_STRATEGY
used for getting recent application code, either
+globally or per-job in the variables
section. If left
+unspecified, the default from project settings will be used.
There are three possible values: clone
, fetch
, and none
.
clone
is the slowest option. It clones the repository from scratch for every
+job, ensuring that the project workspace is always pristine.
variables:
+ GIT_STRATEGY: clone
+fetch
is faster as it re-uses the project workspace (falling back to clone
+if it doesn't exist). git clean
is used to undo any changes made by the last
+job, and git fetch
is used to retrieve commits made since the last job ran.
variables:
+ GIT_STRATEGY: fetch
+none
also re-uses the project workspace, but skips all Git operations
+(including GitLab Runner's pre-clone script, if present). It is mostly useful
+for jobs that operate exclusively on artifacts (e.g., deploy
). Git repository
+data may be present, but it is certain to be out of date, so you should only
+rely on files brought into the project workspace from cache or artifacts.
variables:
+ GIT_STRATEGY: none
+++Requires GitLab Runner v1.10+.
+
The GIT_SUBMODULE_STRATEGY
variable is used to control if / how Git
+submodules are included when fetching the code before a build. You can set them
+globally or per-job in the variables
section.
There are three possible values: none
, normal
, and recursive
:
none
means that submodules will not be included when fetching the project
+code. This is the default, which matches the pre-v1.10 behavior.
normal
means that only the top-level submodules will be included. It is
+equivalent to:
git submodule sync
+git submodule update --init
+recursive
means that all submodules (including submodules of submodules)
+will be included. It is equivalent to:
git submodule sync --recursive
+git submodule update --init --recursive
+Note that for this feature to work correctly, the submodules must be configured
+(in .gitmodules
) with either:
++Introduced in GitLab Runner 9.3
+
The GIT_CHECKOUT
variable can be used when the GIT_STRATEGY
is set to either
+clone
or fetch
to specify whether a git checkout
should be run. If not
+specified, it defaults to true. You can set them globally or per-job in the
+variables
section.
If set to false
, the Runner will:
fetch
- update the repository and leave working copy on
+the current revision,clone
- clone the repository and leave working copy on the
+default branch.Having this setting set to true
will mean that for both clone
and fetch
+strategies the Runner will checkout the working copy to a revision related
+to the CI pipeline:
variables:
+ GIT_STRATEGY: clone
+ GIT_CHECKOUT: "false"
+script:
+ - git checkout master
+ - git merge $CI_BUILD_REF_NAME
+++Introduced in GitLab, it requires GitLab Runner v1.9+.
+
You can set the number for attempts the running job will try to execute each +of the following stages:
+Variable | +Description | +
---|---|
GET_SOURCES_ATTEMPTS | +Number of attempts to fetch sources running a job | +
ARTIFACT_DOWNLOAD_ATTEMPTS | +Number of attempts to download artifacts running a job | +
RESTORE_CACHE_ATTEMPTS | +Number of attempts to restore the cache running a job | +
The default is one single attempt.
+Example:
+variables:
+ GET_SOURCES_ATTEMPTS: 3
+You can set them globally or per-job in the variables
section.
++Introduced in GitLab 8.9 as an experimental feature. May change in future +releases or be removed completely.
+
You can specify the depth of fetching and cloning using GIT_DEPTH
. This allows
+shallow cloning of the repository which can significantly speed up cloning for
+repositories with a large number of commits or old, large binaries. The value is
+passed to git fetch
and git clone
.
++Note: +If you use a depth of 1 and have a queue of jobs or retry +jobs, jobs may fail.
+
Since Git fetching and cloning is based on a ref, such as a branch name, Runners
+can't clone a specific commit SHA. If there are multiple jobs in the queue, or
+you are retrying an old job, the commit to be tested needs to be within the
+Git history that is cloned. Setting too small a value for GIT_DEPTH
can make
+it impossible to run these old commits. You will see unresolved reference
in
+job logs. You should then reconsider changing GIT_DEPTH
to a higher value.
Jobs that rely on git describe
may not work correctly when GIT_DEPTH
is
+set since only part of the Git history is present.
To fetch or clone only the last 3 commits:
+variables:
+ GIT_DEPTH: "3"
+You can set it globally or per-job in the variables
section.
It's possible to use special YAML features like anchors (&
), aliases (*
)
+and map merging (<<
), which will allow you to greatly reduce the complexity
+of .gitlab-ci.yml
.
Read more about the various YAML features.
+++Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
+
If you want to temporarily 'disable' a job, rather than commenting out all the +lines where the job is defined:
+#hidden_job:
+# script:
+# - run test
+you can instead start its name with a dot (.
) and it will not be processed by
+GitLab CI. In the following example, .hidden_job
will be ignored:
.hidden_job:
+ script:
+ - run test
+Use this feature to ignore jobs, or use the +special YAML features and transform the hidden keys +into templates.
+++Introduced in GitLab 8.6 and GitLab Runner v1.1.1.
+
YAML has a handy feature called 'anchors', which lets you easily duplicate +content across your document. Anchors can be used to duplicate/inherit +properties, and is a perfect example to be used with hidden keys +to provide templates for your jobs.
+The following example uses anchors and map merging. It will create two jobs,
+test1
and test2
, that will inherit the parameters of .job_template
, each
+having their own custom script
defined:
.job_template: &job_definition # Hidden key that defines an anchor named 'job_definition'
+ image: ruby:2.1
+ services:
+ - postgres
+ - redis
+
+test1:
+ <<: *job_definition # Merge the contents of the 'job_definition' alias
+ script:
+ - test1 project
+
+test2:
+ <<: *job_definition # Merge the contents of the 'job_definition' alias
+ script:
+ - test2 project
+&
sets up the name of the anchor (job_definition
), <<
means "merge the
+given hash into the current one", and *
includes the named anchor
+(job_definition
again). The expanded version looks like this:
.job_template:
+ image: ruby:2.1
+ services:
+ - postgres
+ - redis
+
+test1:
+ image: ruby:2.1
+ services:
+ - postgres
+ - redis
+ script:
+ - test1 project
+
+test2:
+ image: ruby:2.1
+ services:
+ - postgres
+ - redis
+ script:
+ - test2 project
+Let's see another one example. This time we will use anchors to define two sets
+of services. This will create two jobs, test:postgres
and test:mysql
, that
+will share the script
directive defined in .job_template
, and the services
+directive defined in .postgres_services
and .mysql_services
respectively:
.job_template: &job_definition
+ script:
+ - test project
+
+.postgres_services:
+ services: &postgres_definition
+ - postgres
+ - ruby
+
+.mysql_services:
+ services: &mysql_definition
+ - mysql
+ - ruby
+
+test:postgres:
+ <<: *job_definition
+ services: *postgres_definition
+
+test:mysql:
+ <<: *job_definition
+ services: *mysql_definition
+The expanded version looks like this:
+.job_template:
+ script:
+ - test project
+
+.postgres_services:
+ services:
+ - postgres
+ - ruby
+
+.mysql_services:
+ services:
+ - mysql
+ - ruby
+
+test:postgres:
+ script:
+ - test project
+ services:
+ - postgres
+ - ruby
+
+test:mysql:
+ script:
+ - test project
+ services:
+ - mysql
+ - ruby
+You can see that the hidden keys are conveniently used as templates.
+Triggers can be used to force a rebuild of a specific branch, tag or commit, +with an API call.
+Read more in the triggers documentation.
+If your commit message contains [ci skip]
or [skip ci]
, using any
+capitalization, the commit will be created but the pipeline will be skipped.
Each instance of GitLab CI has an embedded debug tool called Lint, which validates the
+content of your .gitlab-ci.yml
files. You can find the Lint under the page ci/lint
of your
+project namespace (e.g, http://gitlab-example.com/gitlab-org/project-123/-/ci/lint
)
If you get validation error when using specific values (e.g., true
or false
),
+try to quote them, or change them to a different form (e.g., /bin/true
).
Visit the examples README to see a list of examples using GitLab +CI with various languages.
++Discover projects, groups and snippets. Share your projects with others +
++Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
++ +Already have login and password? +Sign in + +
+This document was moved to another location.
+Users have different abilities depending on the access level they have in a +particular group or project. If a user is both in a group's project and the +project itself, the highest permission level is used.
+On public and internal projects the Guest role is not enforced. All users will +be able to create issues, leave comments, and clone or download the project code.
+When a member leaves the team all the assigned Issues and Merge Requests +will be unassigned automatically.
+GitLab administrators receive all permissions.
+To add or import a user, you can follow the +project members documentation.
+See our product handbook on permissions
+NOTE: Note: +In GitLab 11.0, the Master role was renamed to Maintainer.
+The following table depicts the various user permission levels in a project.
+Action | +Guest | +Reporter | +Developer | +Maintainer | +Owner | +
---|---|---|---|---|---|
Create new issue | +✓ | +✓ | +✓ | +✓ | +✓ | +
Create confidential issue | +✓ | +✓ | +✓ | +✓ | +✓ | +
View confidential issues | +(✓) | +✓ | +✓ | +✓ | +✓ | +
Leave comments | +✓ | +✓ | +✓ | +✓ | +✓ | +
Lock issue discussions | ++ | ✓ | +✓ | +✓ | +✓ | +
Lock merge request discussions | ++ | + | ✓ | +✓ | +✓ | +
See a list of jobs | +✓ | +✓ | +✓ | +✓ | +✓ | +
See a job log | +✓ | +✓ | +✓ | +✓ | +✓ | +
Download and browse job artifacts | +✓ | +✓ | +✓ | +✓ | +✓ | +
View wiki pages | +✓ | +✓ | +✓ | +✓ | +✓ | +
Pull project code | ++ | ✓ | +✓ | +✓ | +✓ | +
Download project | ++ | ✓ | +✓ | +✓ | +✓ | +
Assign issues | ++ | ✓ | +✓ | +✓ | +✓ | +
Assign merge requests | ++ | + | ✓ | +✓ | +✓ | +
Label issues and merge requests | ++ | ✓ | +✓ | +✓ | +✓ | +
Create code snippets | ++ | ✓ | +✓ | +✓ | +✓ | +
Manage issue tracker | ++ | ✓ | +✓ | +✓ | +✓ | +
Manage labels | ++ | ✓ | +✓ | +✓ | +✓ | +
See a commit status | ++ | ✓ | +✓ | +✓ | +✓ | +
See a container registry | ++ | ✓ | +✓ | +✓ | +✓ | +
See environments | ++ | ✓ | +✓ | +✓ | +✓ | +
See a list of merge requests | ++ | ✓ | +✓ | +✓ | +✓ | +
Manage related issues [STARTER] + | ++ | ✓ | +✓ | +✓ | +✓ | +
Lock issue discussions | ++ | ✓ | +✓ | +✓ | +✓ | +
Lock merge request discussions | ++ | + | ✓ | +✓ | +✓ | +
Create new environments | ++ | + | ✓ | +✓ | +✓ | +
Stop environments | ++ | + | ✓ | +✓ | +✓ | +
Manage/Accept merge requests | ++ | + | ✓ | +✓ | +✓ | +
Create new merge request | ++ | + | ✓ | +✓ | +✓ | +
Create new branches | ++ | + | ✓ | +✓ | +✓ | +
Push to non-protected branches | ++ | + | ✓ | +✓ | +✓ | +
Force push to non-protected branches | ++ | + | ✓ | +✓ | +✓ | +
Remove non-protected branches | ++ | + | ✓ | +✓ | +✓ | +
Add tags | ++ | + | ✓ | +✓ | +✓ | +
Write a wiki | ++ | + | ✓ | +✓ | +✓ | +
Cancel and retry jobs | ++ | + | ✓ | +✓ | +✓ | +
Create or update commit status | ++ | + | ✓ | +✓ | +✓ | +
Update a container registry | ++ | + | ✓ | +✓ | +✓ | +
Remove a container registry image | ++ | + | ✓ | +✓ | +✓ | +
Create/edit/delete project milestones | ++ | + | ✓ | +✓ | +✓ | +
Use environment terminals | ++ | + | + | ✓ | +✓ | +
Add new team members | ++ | + | + | ✓ | +✓ | +
Push to protected branches | ++ | + | + | ✓ | +✓ | +
Enable/disable branch protection | ++ | + | + | ✓ | +✓ | +
Turn on/off protected branch push for devs | ++ | + | + | ✓ | +✓ | +
Enable/disable tag protections | ++ | + | + | ✓ | +✓ | +
Rewrite/remove Git tags | ++ | + | + | ✓ | +✓ | +
Edit project | ++ | + | + | ✓ | +✓ | +
Add deploy keys to project | ++ | + | + | ✓ | +✓ | +
Configure project hooks | ++ | + | + | ✓ | +✓ | +
Manage Runners | ++ | + | + | ✓ | +✓ | +
Manage job triggers | ++ | + | + | ✓ | +✓ | +
Manage variables | ++ | + | + | ✓ | +✓ | +
Manage GitLab Pages | ++ | + | + | ✓ | +✓ | +
Manage GitLab Pages domains and certificates | ++ | + | + | ✓ | +✓ | +
Remove GitLab Pages | ++ | + | + | + | ✓ | +
Manage clusters | ++ | + | + | ✓ | +✓ | +
Edit comments (posted by any user) | ++ | + | + | ✓ | +✓ | +
Switch visibility level | ++ | + | + | + | ✓ | +
Transfer project to another namespace | ++ | + | + | + | ✓ | +
Remove project | ++ | + | + | + | ✓ | +
Delete issues | ++ | + | + | + | ✓ | +
Remove pages | ++ | + | + | + | ✓ | +
Force push to protected branches | ++ | + | + | + | + |
Remove protected branches | ++ | + | + | + | + |
View project Audit Events | ++ | + | + | ✓ | +✓ | +
Project features like wiki and issues can be hidden from users depending on +which visibility level you select on project settings.
+To prevent people from messing with history or pushing code without +review, we've created protected branches. Read through the documentation on +protected branches +to learn more.
+Additionally, you can allow or forbid users with Maintainer and/or +Developer permissions to push to a protected branch. Read through the documentation on +Allowed to Merge and Allowed to Push settings +to learn more.
+Find the current permissions on the Cycle Analytics dashboard on +the documentation on Cycle Analytics permissions.
+Developers and users with higher permission level can use all +the functionality of the Issue Board, that is create/delete lists +and drag issues around. Read though the +documentation on Issue Boards permissions +to learn more.
+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.
+Read through the documentation on permissions for File Locking to learn more.
+Confidential issues can be accessed by reporters and higher permission levels, +as well as by guest users that create a confidential issue. To learn more, +read through the documentation on permissions and access to confidential issues.
+NOTE: Note: +In GitLab 11.0, the Master role was renamed to Maintainer.
+Any user can remove themselves from a group, unless they are the last Owner of +the group. The following table depicts the various user permission levels in a +group.
+Action | +Guest | +Reporter | +Developer | +Maintainer | +Owner | +
---|---|---|---|---|---|
Browse group | +✓ | +✓ | +✓ | +✓ | +✓ | +
Edit group | ++ | + | + | + | ✓ | +
Create subgroup | ++ | + | + | + | ✓ | +
Create project in group | ++ | + | + | ✓ | +✓ | +
Manage group members | ++ | + | + | + | ✓ | +
Remove group | ++ | + | + | + | ✓ | +
Manage group labels | ++ | ✓ | +✓ | +✓ | +✓ | +
Create/edit/delete group milestones | ++ | + | ✓ | +✓ | +✓ | +
View private group epic [ULTIMATE] + | ++ | ✓ | +✓ | +✓ | +✓ | +
View internal group epic [ULTIMATE] + | +✓ | +✓ | +✓ | +✓ | +✓ | +
View public group epic [ULTIMATE] + | +✓ | +✓ | +✓ | +✓ | +✓ | +
Create/edit group epic [ULTIMATE] + | ++ | ✓ | +✓ | +✓ | +✓ | +
Delete group epic [ULTIMATE] + | ++ | + | + | + | ✓ | +
View group Audit Events | ++ | + | + | + | ✓ | +
When you add a member to a subgroup, they inherit the membership and +permission level from the parent group. This model allows access to +nested groups if you have membership in one of its parents.
+To learn more, read through the documentation on +subgroups memberships.
+In cases where it is desired that a user has access only to some internal or +private projects, there is the option of creating External Users. This +feature may be useful when for example a contractor is working on a given +project and should only have access to that project.
+External users can only access projects to which they are explicitly granted +access, thus hiding all other internal or private ones from them. Access can be +granted by adding the user as member to the project or group.
+They will, like usual users, receive a role in the project or group with all +the abilities that are mentioned in the table above. They cannot however create +groups or projects, and they have the same access as logged out users in all +other cases.
+An administrator can flag a user as external through the API +or by checking the checkbox on the admin panel. As an administrator, navigate +to Admin > Users to create a new user or edit an existing one. There, you +will find the option to flag the user as external.
+By default new users are not set as external users. This behavior can be changed +by an administrator under Admin > Application Settings.
+++Introduced in GitLab Premium 8.17.
+
Auditor users are given read-only access to all projects, groups, and other +resources on the GitLab instance.
+An Auditor user should be able to access all projects and groups of a GitLab instance +with the permissions described on the documentation on auditor users permissions.
+Read more about Auditor users.
+Project features like wiki and issues can be hidden from users depending on +which visibility level you select on project settings.
+NOTE: Note: +In GitLab 11.0, the Master role was renamed to Maintainer.
+GitLab CI/CD permissions rely on the role the user has in GitLab. There are four +permission levels in total:
+The admin user can perform any action on GitLab CI/CD in scope of the GitLab
+instance and project. In addition, all admins can use the admin interface under
+/admin/runners
.
Action | +Guest, Reporter | +Developer | +Maintainer | +Admin | +
---|---|---|---|---|
See commits and jobs | +✓ | +✓ | +✓ | +✓ | +
Retry or cancel job | ++ | ✓ | +✓ | +✓ | +
Erase job artifacts and trace | ++ | ✓ | +✓ | +✓ | +
Remove project | ++ | + | ✓ | +✓ | +
Create project | ++ | + | ✓ | +✓ | +
Change project configuration | ++ | + | ✓ | +✓ | +
Add specific runners | ++ | + | ✓ | +✓ | +
Add shared runners | ++ | + | + | ✓ | +
See events in the system | ++ | + | + | ✓ | +
Admin interface | ++ | + | + | ✓ | +
NOTE: Note: +In GitLab 11.0, the Master role was renamed to Maintainer.
+++Note: +GitLab 8.12 has a completely redesigned job permissions system. +Read all about the new model and its implications.
+
This table shows granted privileges for jobs triggered by specific types of +users:
+Action | +Guest, Reporter | +Developer | +Maintainer | +Admin | +
---|---|---|---|---|
Run CI job | ++ | ✓ | +✓ | +✓ | +
Clone source and LFS from current project | ++ | ✓ | +✓ | +✓ | +
Clone source and LFS from public projects | ++ | ✓ | +✓ | +✓ | +
Clone source and LFS from internal projects | ++ | ✓ | +✓ | +✓ | +
Clone source and LFS from private projects | ++ | ✓ | +✓ | +✓ | +
Push source and LFS | ++ | + | + | + |
Pull container images from current project | ++ | ✓ | +✓ | +✓ | +
Pull container images from public projects | ++ | ✓ | +✓ | +✓ | +
Pull container images from internal projects | ++ | ✓ | +✓ | +✓ | +
Pull container images from private projects | ++ | ✓ | +✓ | +✓ | +
Push container images to current project | ++ | ✓ | +✓ | +✓ | +
Push container images to other projects | ++ | + | + | + |
GitLab 8.12 has a completely redesigned job permissions system. To learn more, +read through the documentation on the new CI/CD permissions model.
+The permission to merge or push to protected branches is used to define if a user can +run CI/CD pipelines and execute actions on jobs that are related to those branches.
+See Security on protected branches +for details about the pipelines security model.
+Since GitLab 8.15, LDAP user permissions can now be manually overridden by an admin user. +Read through the documentation on LDAP users permissions to learn more.
+Version management with git makes branching and merging much easier than older versioning systems such as SVN. +This allows a wide variety of branching strategies and workflows. +Almost all of these are an improvement over the methods used before git. +But many organizations end up with a workflow that is not clearly defined, overly complex or not integrated with issue tracking systems. +Therefore we propose the GitLab flow as clearly defined set of best practices. +It combines feature driven development and feature branches with issue tracking.
+Organizations coming to git from other version control systems frequently find it hard to develop an effective workflow. +This article describes the GitLab flow that integrates the git workflow with an issue tracking system. +It offers a simple, transparent and effective way to work with git.
+ +When converting to git you have to get used to the fact that there are three steps before a commit is shared with colleagues. +Most version control systems have only one step, committing from the working copy to a shared server. +In git you add files from the working copy to the staging area. After that you commit them to the local repo. +The third step is pushing to a shared remote repository. +After getting used to these three steps the branching model becomes the challenge.
+ +Since many organizations new to git have no conventions how to work with it, it can quickly become a mess. +The biggest problem they run into is that many long running branches that each contain part of the changes are around. +People have a hard time figuring out which branch they should develop on or deploy to production. +Frequently the reaction to this problem is to adopt a standardized pattern such as git flow and GitHub flow. +We think there is still room for improvement and will detail a set of practices we call GitLab flow.
+Git flow was one of the first proposals to use git branches and it has gotten a lot of attention. +It advocates a master branch and a separate develop branch as well as supporting branches for features, releases and hotfixes. +The development happens on the develop branch, moves to a release branch and is finally merged into the master branch. +Git flow is a well defined standard but its complexity introduces two problems. +The first problem is that developers must use the develop branch and not master, master is reserved for code that is released to production. +It is a convention to call your default branch master and to mostly branch from and merge to this. +Since most tools automatically make the master branch the default one and display that one by default it is annoying to have to switch to another one. +The second problem of git flow is the complexity introduced by the hotfix and release branches. +These branches can be a good idea for some organizations but are overkill for the vast majority of them. +Nowadays most organizations practice continuous delivery which means that your default branch can be deployed. +This means that hotfix and release branches can be prevented including all the ceremony they introduce. +An example of this ceremony is the merging back of release branches. +Though specialized tools do exist to solve this, they require documentation and add complexity. +Frequently developers make a mistake and for example changes are only merged into master and not into the develop branch. +The root cause of these errors is that git flow is too complex for most of the use cases. +And doing releases doesn't automatically mean also doing hotfixes.
+In reaction to git flow a simpler alternative was detailed, GitHub flow. +This flow has only feature branches and a master branch. +This is very simple and clean, many organizations have adopted it with great success. +Atlassian recommends a similar strategy although they rebase feature branches. +Merging everything into the master branch and deploying often means you minimize the amount of code in 'inventory' which is in line with the lean and continuous delivery best practices. +But this flow still leaves a lot of questions unanswered regarding deployments, environments, releases and integrations with issues. +With GitLab flow we offer additional guidance for these questions.
+GitHub flow does assume you are able to deploy to production every time you merge a feature branch. +This is possible for e.g. SaaS applications, but there are many cases where this is not possible. +One would be a situation where you are not in control of the exact release moment, for example an iOS application that needs to pass App Store validation. +Another example is when you have deployment windows (workdays from 10am to 4pm when the operations team is at full capacity) but you also merge code at other times. +In these cases you can make a production branch that reflects the deployed code. +You can deploy a new version by merging in master to the production branch. +If you need to know what code is in production you can just checkout the production branch to see. +The approximate time of deployment is easily visible as the merge commit in the version control system. +This time is pretty accurate if you automatically deploy your production branch. +If you need a more exact time you can have your deployment script create a tag on each deployment. +This flow prevents the overhead of releasing, tagging and merging that is common to git flow.
+It might be a good idea to have an environment that is automatically updated to the master branch. +Only in this case, the name of this environment might differ from the branch name. +Suppose you have a staging environment, a pre-production environment and a production environment. +In this case the master branch is deployed on staging. When someone wants to deploy to pre-production they create a merge request from the master branch to the pre-production branch. +And going live with code happens by merging the pre-production branch into the production branch. +This workflow where commits only flow downstream ensures that everything has been tested on all environments. +If you need to cherry-pick a commit with a hotfix it is common to develop it on a feature branch and merge it into master with a merge request, do not delete the feature branch. +If master is good to go (it should be if you are practicing continuous delivery) you then merge it to the other branches. +If this is not possible because more manual testing is required you can send merge requests from the feature branch to the downstream branches.
+Only in case you need to release software to the outside world you need to work with release branches. +In this case, each branch contains a minor version (2-3-stable, 2-4-stable, etc.). +The stable branch uses master as a starting point and is created as late as possible. +By branching as late as possible you minimize the time you have to apply bug fixes to multiple branches. +After a release branch is announced, only serious bug fixes are included in the release branch. +If possible these bug fixes are first merged into master and then cherry-picked into the release branch. +This way you can't forget to cherry-pick them into master and encounter the same bug on subsequent releases. +This is called an 'upstream first' policy that is also practiced by Google and Red Hat. +Every time a bug-fix is included in a release branch the patch version is raised (to comply with Semantic Versioning) by setting a new tag. +Some projects also have a stable branch that points to the same commit as the latest released branch. +In this flow it is not common to have a production branch (or git flow master branch).
+Merge or pull requests are created in a git management application and ask an assigned person to merge two branches. +Tools such as GitHub and Bitbucket choose the name pull request since the first manual action would be to pull the feature branch. +Tools such as GitLab and others choose the name merge request since that is the final action that is requested of the assignee. +In this article we'll refer to them as merge requests.
+If you work on a feature branch for more than a few hours it is good to share the intermediate result with the rest of the team. +This can be done by creating a merge request without assigning it to anyone, instead you mention people in the description or a comment (/cc @mark @susan). +This means it is not ready to be merged but feedback is welcome. +Your team members can comment on the merge request in general or on specific lines with line comments. +The merge requests serves as a code review tool and no separate tools such as Gerrit and reviewboard should be needed. +If the review reveals shortcomings anyone can commit and push a fix. +Commonly the person to do this is the creator of the merge/pull request. +The diff in the merge/pull requests automatically updates when new commits are pushed on the branch.
+When you feel comfortable with it to be merged you assign it to the person that knows most about the codebase you are changing and mention any other people you would like feedback from. +There is room for more feedback and after the assigned person feels comfortable with the result the branch is merged. +If the assigned person does not feel comfortable they can close the merge request without merging.
+In GitLab it is common to protect the long-lived branches (e.g. the master branch) so that normal developers can't modify these protected branches. +So if you want to merge it into a protected branch you assign it to someone with maintainer authorizations.
+GitLab flow is a way to make the relation between the code and the issue tracker more transparent.
+Any significant change to the code should start with an issue where the goal is described. +Having a reason for every code change is important to inform everyone on the team and to help people keep the scope of a feature branch small. +In GitLab each change to the codebase starts with an issue in the issue tracking system. +If there is no issue yet it should be created first provided there is significant work involved (more than 1 hour). +For many organizations this will be natural since the issue will have to be estimated for the sprint. +Issue titles should describe the desired state of the system, e.g. "As an administrator I want to remove users without receiving an error" instead of "Admin can't remove users.".
+When you are ready to code you start a branch for the issue from the master branch. +The name of this branch should start with the issue number, for example '15-require-a-password-to-change-it'.
+When you are done or want to discuss the code you open a merge request.
+This is an online place to discuss the change and review the code.
+Opening a merge request is a manual action since you do not always want to merge a new branch you push, it could be a long-running environment or release branch.
+If you open the merge request but do not assign it to anyone it is a 'Work In Progress' merge request.
+These are used to discuss the proposed implementation but are not ready for inclusion in the master branch yet.
+Pro tip: Start the title of the merge request with [WIP]
or WIP:
to prevent it from being merged before it's ready.
When the author thinks the code is ready the merge request is assigned to reviewer. +The reviewer presses the merge button when they think the code is ready for inclusion in the master branch. +In this case the code is merged and a merge commit is generated that makes this event easily visible later on. +Merge requests always create a merge commit even when the commit could be added without one. +This merge strategy is called 'no fast-forward' in git. +After the merge the feature branch is deleted since it is no longer needed, in GitLab this deletion is an option when merging.
+Suppose that a branch is merged but a problem occurs and the issue is reopened. +In this case it is no problem to reuse the same branch name since it was deleted when the branch was merged. +At any time there is at most one branch for every issue. +It is possible that one feature branch solves more than one issue.
+Linking to issues can happen by mentioning them in commit messages (fixes #14, closes #67, etc.) or in the merge request description. +GitLab then creates links to the mentioned issues and creates comments in the corresponding issues linking back to the merge request.
+These issues are closed once code is merged into the default branch.
+If you only want to make the reference without closing the issue you can also just mention it: "Duck typing is preferred. #12".
+If you have an issue that spans across multiple repositories, the best thing is to create an issue for each repository and link all issues to a parent issue.
+With git you can use an interactive rebase (rebase -i
) to squash multiple commits into one and reorder them.
+In GitLab EE and .com you can also rebase before merge from the web interface.
+This functionality is useful if you made a couple of commits for small changes during development and want to replace them with a single commit or if you want to make the order more logical.
+However you should never rebase commits you have pushed to a remote server.
+Somebody can have referred to the commits or cherry-picked them.
+When you rebase you change the identifier (SHA-1) of the commit and this is confusing.
+If you do that the same change will be known under multiple identifiers and this can cause much confusion.
+If people already reviewed your code it will be hard for them to review only the improvements you made since then if you have rebased everything into one commit.
+Another reasons not to rebase is that you lose authorship information, maybe someone created a merge request, another person pushed a commit on there to improve it and a third one merged it.
+In this case rebasing all the commits into one prevent the other authors from being properly attributed and sharing part of the git blame.
People are encouraged to commit often and to frequently push to the remote repository so other people are aware what everyone is working on. +This will lead to many commits per change which makes the history harder to understand. +But the advantages of having stable identifiers outweigh this drawback. +And to understand a change in context one can always look at the merge commit that groups all the commits together when the code is merged into the master branch.
+After you merge multiple commits from a feature branch into the master branch this is harder to undo. +If you had squashed all the commits into one you could have just reverted this commit but as we indicated you should not rebase commits after they are pushed. +Fortunately reverting a merge made some time ago can be done with git. +This however, requires having specific merge commits for the commits your want to revert. +If you revert a merge and you change your mind, revert the revert instead of merging again since git will not allow you to merge the code again otherwise.
+Being able to revert a merge is a good reason always to create a merge commit when you merge manually with the --no-ff
option.
+Git management software will always create a merge commit when you accept a merge request.
With git you can also rebase your feature branch commits to order them after the commits on the master branch. +This prevents creating a merge commit when merging master into your feature branch and creates a nice linear history. +However, just like with squashing you should never rebase commits you have pushed to a remote server. +This makes it impossible to rebase work in progress that you already shared with your team which is something we recommend. +When using rebase to keep your feature branch updated you need to resolve similar conflicts again and again. +You can reuse recorded resolutions (rerere) sometimes, but without rebasing you only have to solve the conflicts one time and you’re set. +There has to be a better way to avoid many merge commits.
+The way to prevent creating many merge commits is to not frequently merge master into the feature branch.
+We'll discuss the three reasons to merge in master: leveraging code, merge conflicts, and long running branches.
+If you need to leverage some code that was introduced in master after you created the feature branch you can sometimes solve this by just cherry-picking a commit.
+If your feature branch has a merge conflict, creating a merge commit is a normal way of solving this.
+You can prevent some merge conflicts by using gitattributes for files that can be in a random order.
+For example in GitLab our changelog file is specified in .gitattributes as CHANGELOG.md merge=union
so that there are fewer merge conflicts in it.
+The last reason for creating merge commits is having long lived branches that you want to keep up to date with the latest state of the project.
+Martin Fowler, in his article about feature branches talks about this Continuous Integration (CI).
+At GitLab we are guilty of confusing CI with branch testing. Quoting Martin Fowler: "I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit.
+That's continuous building, and a Good Thing, but there's no integration, so it's not CI.".
+The solution to prevent many merge commits is to keep your feature branches short-lived, the vast majority should take less than one day of work.
+If your feature branches commonly take more than a day of work, look into ways to create smaller units of work and/or use feature toggles.
+As for the long running branches that take more than one day there are two strategies.
+In a CI strategy you can merge in master at the start of the day to prevent painful merges at a later time.
+In a synchronization point strategy you only merge in from well defined points in time, for example a tagged release.
+This strategy is advocated by Linus Torvalds because the state of the code at these points is better known.
In conclusion, we can say that you should try to prevent merge commits, but not eliminate them. +Your codebase should be clean but your history should represent what actually happened. +Developing software happen in small messy steps and it is OK to have your history reflect this. +You can use tools to view the network graphs of commits and understand the messy history that created your code. +If you rebase code the history is incorrect, and there is no way for tools to remedy this because they can't deal with changing commit identifiers.
+It is common to voice approval or disapproval by using +1 or -1. In GitLab you +can use emojis to give a virtual high five on issues and merge requests.
+We recommend that people push their feature branches frequently, even when they are not ready for review yet. +By doing this you prevent team members from accidentally starting to work on the same issue. +Of course this situation should already be prevented by assigning someone to the issue in the issue tracking software. +However sometimes one of the two parties forgets to assign someone in the issue tracking software. +After a branch is merged it should be removed from the source control software. +In GitLab and similar systems this is an option when merging. +This ensures that the branch overview in the repository management software shows only work in progress. +This also ensures that when someone reopens the issue a new branch with the same name can be used without problem. +When you reopen an issue you need to create a new merge request.
+We recommend to commit early and often. +Each time you have a functioning set of tests and code a commit can be made. +The advantage is that when an extension or refactor goes wrong it is easy to revert to a working version. +This is quite a change for programmers that used SVN before, they used to commit when their work was ready to share. +The trick is to use the merge/pull request with multiple commits when your work is ready to share. +The commit message should reflect your intention, not the contents of the commit. +The contents of the commit can be easily seen anyway, the question is why you did it. +An example of a good commit message is: "Combine templates to dry up the user views.". +Some words that are bad commit messages because they don't contain much information are: change, improve and refactor. +The word fix or fixes is also a red flag, unless it comes after the commit sentence and references an issue number. +To see more information about the formatting of commit messages please see this great blog post by Tim Pope.
+In old workflows the Continuous Integration (CI) server commonly ran tests on the master branch only. +Developers had to ensure their code did not break the master branch. +When using GitLab flow developers create their branches from this master branch so it is essential it is green. +Therefore each merge request must be tested before it is accepted. +CI software like Travis and GitLab CI show the build results right in the merge request itself to make this easy. +One drawback is that they are testing the feature branch itself and not the merged result. +What one can do to improve this is to test the merged result itself. +The problem is that the merge result changes every time something is merged into master. +Retesting on every commit to master is computationally expensive and means you are more frequently waiting for test results. +If there are no merge conflicts and the feature branches are short lived the risk is acceptable. +If there are merge conflicts you merge the master branch into the feature branch and the CI server will rerun the tests. +If you have long lived feature branches that last for more than a few days you should make your issues smaller.
+When initiating a feature branch, always start with an up to date master to branch off from. +If you know beforehand that your work absolutely depends on another branch you can also branch from there. +If you need to merge in another branch after starting explain the reason in the merge commit. +If you have not pushed your commits to a shared location yet you can also rebase on master or another feature branch. +Do not merge in upstream if your code will work and merge cleanly without doing so, Linus even says that you should never merge in upstream at random points, only at major releases. +Merging only when needed prevents creating merge commits in your feature branch that later end up littering the master history.
+GitLab integrates with multiple third-party services to allow external issue +trackers and external authentication.
+See the documentation below for details on how to configure these services.
+++GitLab Enterprise Edition contains advanced Jenkins support.
+
Integration with services such as Campfire, Flowdock, Gemnasium, HipChat, +Pivotal Tracker, and Slack are available in the form of a Project Service.
+When trying to integrate GitLab with services that are using self-signed certificates, +it is very likely that SSL certificate errors will occur on different parts of the +application, most likely Sidekiq. There are 2 approaches you can take to solve this:
+OS main trusted chain
+This resource +has all the information you need to add a certificate to the main trusted chain.
+This answer +at Super User also has relevant information.
+Omnibus Trusted Chain
+Install the self signed certificate or custom certificate authorities +in to GitLab Omnibus.
+It is enough to concatenate the certificate to the main trusted certificate +however it may be overwritten during upgrades:
+cat jira.pem >> /opt/gitlab/embedded/ssl/certs/cacert.pem
+After that restart GitLab with:
+sudo gitlab-ctl restart
+The GitLab Issue Tracker is an advanced and complete tool +for tracking the evolution of a new idea or the process +of solving a problem.
+It allows you, your team, and your collaborators to share +and discuss proposals before and while implementing them.
+GitLab Issues and the GitLab Issue Tracker are available in all +GitLab Products as +part of the GitLab Workflow.
+Issues can have endless applications. Just to exemplify, these are +some cases for which creating issues are most used:
+See also the blog post "Always start a discussion with an issue".
+For instance, let's assume you have a public project but want to start a discussion on something +you don't want to be public. With Confidential Issues, +you can discuss private matters among the project members, and still keep +your project public, open to collaboration.
+With Multiple Assignees for Issues, +available in GitLab Starter +you can streamline collaboration and allow shared responsibilities to be clearly displayed. +All assignees are shown across your workflows and receive notifications (as they +would as single assignees), simplifying communication and ownership.
+Create issue templates to make collaboration consistent and +containing all information you need. For example, you can create a template +for feature proposals and another one for bug reports.
+The Issue Tracker is the collection of opened and closed issues created in a project. +It is available for all projects, from the moment the project is created.
+Find the issue tracker by navigating to your Project's homepage > Issues.
+When you access your project's issues, GitLab will present them in a list, +and you can use the tabs available to quickly filter by open and closed issues.
+ +You can also search and filter the results more deeply with GitLab's search capacities.
+View issues in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to Group > Issues to view these issues. This view also has the open and closed issues tabs.
+ +The image bellow illustrates how an issue looks like:
+ +Learn more about it on the GitLab Issues Functionalities documentation.
+Read through the documentation on creating issues.
+Learn distinct ways to close issues in GitLab.
+Read through the documentation on moving issues.
+Read through the documentation on deleting issues
+Learn more about it on the GitLab Issues Functionalities documentation.
+Learn how to find an issue by searching for and filtering them.
+Whenever you want to keep the discussion presented in a +issue within your team only, you can make that +issue confidential. Even if your project +is public, that issue will be preserved. The browser will +respond with a 404 error whenever someone who is not a project +member with at least Reporter level tries to +access that issue's URL.
+Learn more about them on the confidential issues documentation.
+Create templates for every new issue. They will be available from +the dropdown menu Choose a template when you create a new issue:
+ +Learn more about them on the issue templates documentation.
+Learn more about crosslinking issues and merge requests.
+The GitLab Issue Board is a way to +enhance your workflow by organizing and prioritizing issues in GitLab.
+ +Find GitLab Issue Boards by navigating to your Project's Dashboard > Issues > Board.
+Read through the documentation for Issue Boards +to find out more about this feature.
+With GitLab Starter, you can also +create various boards per project with Multiple Issue Boards.
+Alternatively to GitLab's built-in Issue Tracker, you can also use an external +tracker such as Jira, Redmine, +or Bugzilla.
+Read through the API documentation.
+Find out about bulk editing issues.
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+bin/changelog
Gemfile
guidelines+Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+++Notes:
++
+- +Introduced in GitLab 8.9.
+- Importing will not be possible if the import instance version differs from +that of the exporter.
+- For GitLab admins, please read through Project import/export administration.
+- For existing installations, the project import option has to be enabled in +application settings (
+/admin/application_settings
) under 'Import sources'. +Ask your administrator if you don't see the GitLab export button when +creating a new project.- Starting with GitLab 10.0, administrators can disable the project export option +on the GitLab instance in application settings (
+/admin/application_settings
) +under 'Visibility and Access Controls'.- You can find some useful raketasks if you are an administrator in the +import_export +raketask.
+- The exports are stored in a temporary shared directory and are deleted +every 24 hours by a specific worker.
+- Group members will get exported as project members, as long as the user has +maintainer or admin access to the group where the exported project lives. An admin +in the import side is required to map the users, based on email or username. +Otherwise, a supplementary comment is left to mention the original author and +the MRs, notes or issues will be owned by the importer.
+- Control project Import/Export with the API.
+
Existing projects running on any GitLab instance or GitLab.com can be exported +with all their related data and be moved into a new GitLab instance.
+GitLab version | +Import/Export version | +
---|---|
11.1 to current | +0.2.4 | +
10.8 | +0.2.3 | +
10.4 | +0.2.2 | +
10.3 | +0.2.1 | +
10.0 | +0.2.0 | +
9.4.0 | +0.1.8 | +
9.2.0 | +0.1.7 | +
8.17.0 | +0.1.6 | +
8.13.0 | +0.1.5 | +
8.12.0 | +0.1.4 | +
8.10.3 | +0.1.3 | +
8.10.0 | +0.1.2 | +
8.9.5 | +0.1.1 | +
8.9.0 | +0.1.0 | +
++The table reflects what GitLab version we updated the Import/Export version at. +For instance, 8.10.3 and 8.11 will have the same Import/Export version (0.1.3) +and the exports between them will be compatible.
+
The following items will be exported:
+The following items will NOT be exported:
+Go to the project settings page by clicking on Edit Project:
+ +Scroll down to find the Export project button:
+ +Once the export is generated, you should receive an e-mail with a link to +download the file:
+ +Alternatively, you can come back to the project settings and download the +file from there, or generate a new export. Once the file available, the page +should show the Download export button:
+ +The new GitLab project import feature is at the far right of the import +options when creating a New Project. Make sure you are in the right namespace +and you have entered a project name. Click on GitLab export:
+ +You can see where the project will be imported to. You can now select file +exported previously:
+ +Click on Import project to begin importing. Your newly imported project +page will appear soon.
++Discover projects, groups and snippets. Share your projects with others +
+GitLab's Trello Power-Up enables you to seamlessly attach +GitLab merge requests to Trello cards.
+ +In order to get started, you will need to configure your Power-Up.
+In Trello:
+Power-Ups
to see a listing of all the available Power-UpsGitLab
and select the Enable
buttonSettings
(gear) iconAuthorize Account
+In this popup, fill in your API URL
and Personal Access Token
. After that, you will be able to attach any merge request to any Trello card on your selected Trello board.
Your API URL should be your GitLab instance URL with /api/v4
appended in the end of the URL.
+For example, if your GitLab instance URL is https://gitlab.com
, your API URL would be https://gitlab.com/api/v4
.
+If your instance's URL is https://example.com
, your API URL will be https://example.com/api/v4
.
Your GitLab's personal access token will enable your GitLab account to be accessed +from Trello.
+++Find it in GitLab by clicking on your avatar (upright corner), from which you access +your user Settings > Access Tokens.
+
Learn more about generating a personal access token in the +Personal Access Token Documentation. +Don't forget to check the API scope checkbox!
+Try refreshing the page, or going back and attempting the action again.
+Please contact your GitLab administrator if this problem persists.
+Go back ++Discover projects, groups and snippets. Share your projects with others +
+++Introduced in GitLab 10.1.
+
Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes +cluster in a few steps.
+With one or more Kubernetes clusters associated to your project, you can use +Review Apps, deploy your applications, run +your pipelines, use it with Auto DevOps, +and much more, all from within GitLab.
+There are two options when adding a new cluster to your project; either associate +your account with Google Kubernetes Engine (GKE) so that you can create new +clusters from within GitLab, +or provide the credentials to an existing Kubernetes cluster.
+TIP: Tip: +Every new Google Cloud Platform (GCP) account receives $300 in credit upon sign up, +and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's +Google Kubernetes Engine Integration. All you have to do is follow this link and apply for credit.
+NOTE: Note: +The Google authentication integration must +be enabled in GitLab at the instance level. If that's not the case, ask your +GitLab administrator to enable it. On GitLab.com, this is enabled.
+Before creating your first cluster on Google Kubernetes Engine with GitLab's +integration, make sure the following requirements are met:
+If all of the above requirements are met, you can proceed to create and add a +new Kubernetes cluster to your project:
+Navigate to your project's Operations > Kubernetes page.
+NOTE: Note: +You need Maintainer permissions and above to access the Kubernetes page.
+Click on Add Kubernetes cluster.
+Click on Create with Google Kubernetes Engine.
+Connect your Google account if you haven't done already by clicking the +Sign in with Google button.
+From there on, choose your cluster's settings:
+After a couple of minutes, your cluster will be ready to go. You can now proceed +to install some pre-defined applications.
+To add an existing Kubernetes cluster to your project:
+Navigate to your project's Operations > Kubernetes page.
+NOTE: Note: +You need Maintainer permissions and above to access the Kubernetes page.
+Click on Add Kubernetes cluster.
+Click on Add an existing Kubernetes cluster and fill in the details:
+https://kubernetes.example.com
rather than https://kubernetes.example.com/api/v1
.ca.crt
contents here.namespace
. If you don't have a service token yet,
+you can follow the
+Kubernetes documentation
+to create one. You can also view or create service tokens in the
+Kubernetes dashboard
+(under Config > Secrets). The account that will issue the service token
+must have admin privileges on the cluster.
+default
.default
as the project namespace.Finally, click the Create Kubernetes cluster button.
+After a couple of minutes, your cluster will be ready to go. You can now proceed +to install some pre-defined applications.
+CAUTION: Important: +The whole cluster security is based on a model where developers +are trusted, so only trusted users should be allowed to control your clusters.
+The default cluster configuration grants access to a wide set of +functionalities needed to successfully build and deploy a containerized +application. Bare in mind that the same credentials are used for all the +applications running on the cluster.
+When GitLab creates the cluster, it enables and uses the legacy +Attribute-based access control (ABAC). +The newer RBAC +authorization will be supported in a +future release.
+GitLab Runners have the privileged mode +enabled by default, which allows them to execute special commands and running +Docker in Docker. This functionality is needed to run some of the Auto DevOps +jobs. This implies the containers are running in privileged mode and you should, +therefore, be aware of some important details.
+The privileged flag gives all capabilities to the running container, which in
+turn can do almost everything that the host can do. Be aware of the
+inherent security risk associated with performing docker run
operations on
+arbitrary images as they effectively have root access.
If you don't want to use GitLab Runner in privileged mode, first make sure that +you don't have it installed via the applications, and then use the +Runner's Helm chart to +install it manually.
+GitLab provides a one-click install for various applications which will be +added directly to your configured cluster. Those applications are needed for +Review Apps and deployments.
+NOTE: Note:
+The applications will be installed in a dedicated namespace called
+gitlab-managed-apps
. In case you have added an existing Kubernetes cluster
+with Tiller already installed, you should be careful as GitLab cannot
+detect it. By installing it via the applications will result into having it
+twice, which can lead to confusion during deployments.
Application | +GitLab version | +Description | +
---|---|---|
Helm Tiller | +10.2+ | +Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the helm CLI in a safe environment. |
+
Ingress | +10.2+ | +Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use Auto DevOps or deploy your own web apps. | +
Prometheus | +10.4+ | +Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications. | +
GitLab Runner | +10.6+ | +GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with GitLab CI/CD, the open-source continuous integration service included with GitLab that coordinates the jobs. When installing the GitLab Runner via the applications, it will run in privileged mode by default. Make sure you read the security implications before doing so. | +
JupyterHub | +11.0+ | ++JupyterHub is a multi-user service for managing notebooks across a team. Jupyter Notebooks provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. Note: Authentication will be enabled for any user of the GitLab server via OAuth2. HTTPS will be supported in a future release. | +
NOTE: Note: +You need a load balancer installed in your cluster in order to obtain the +external IP address with the following procedure. It can be deployed using the +Ingress application.
+In order to publish your web application, you first need to find the external IP +address associated to your load balancer.
+++Introduced in GitLab 10.6.
+
If you installed the Ingress via the Applications, +you should see the Ingress IP address on this same page within a few minutes. +If you don't see this, GitLab might not be able to determine the IP address of +your ingress application in which case you should manually determine it.
+If the cluster is on GKE, click on the Google Kubernetes Engine link in the
+Advanced settings, or go directly to the
+Google Kubernetes Engine dashboard
+and select the proper project and cluster. Then click on Connect and execute
+the gcloud
command in a local terminal or using the Cloud Shell.
If the cluster is not on GKE, follow the specific instructions for your
+Kubernetes provider to configure kubectl
with the right credentials.
If you installed the Ingress via the Applications, +run the following command:
+kubectl get svc --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip} '
+Otherwise, you can list the IP addresses of all load balancers:
+kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} '
+++Note: Some Kubernetes clusters return a hostname instead, like Amazon EKS. For these platforms, run:
++kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}".
The output is the external IP address of your cluster. This information can then +be used to set up DNS entries and forwarding rules that allow external access to +your deployed applications.
+By default, an ephemeral external IP address is associated to the cluster's load +balancer. If you associate the ephemeral IP with your DNS and the IP changes, +your apps will not be able to be reached, and you'd have to change the DNS +record again. In order to avoid that, you should change it into a static +reserved IP.
+Read how to promote an ephemeral external IP address in GKE.
+Once you've set up the static IP, you should associate it to a wildcard DNS
+record, in order to be able
+to reach your apps. This heavily depends on your domain provider, but in case
+you aren't sure, just create an A record with a wildcard host like
+*.example.com.
.
NOTE: Note: +This is only available for GitLab Premium where you can add more than +one Kubernetes cluster.
+When adding more than one Kubernetes clusters to your project, you need to +differentiate them with an environment scope. The environment scope associates +clusters and environments in an 1:1 relationship +similar to how the +environment-specific variables +work.
+The default environment scope is *
, which means all jobs, regardless of their
+environment, will use that cluster. Each scope can only be used by a single
+cluster in a project, and a validation error will occur if otherwise.
+Also, jobs that don't have an environment keyword set will not be able to access any cluster.
For example, let's say the following Kubernetes clusters exist in a project:
+Cluster | +Environment scope | +
---|---|
Development | +* |
+
Staging | +staging/* |
+
Production | +production/* |
+
And the following environments are set in .gitlab-ci.yml
:
stages:
+- test
+- deploy
+
+test:
+ stage: test
+ script: sh test
+
+deploy to staging:
+ stage: deploy
+ script: make deploy
+ environment:
+ name: staging/$CI_COMMIT_REF_NAME
+ url: https://staging.example.com/
+
+deploy to production:
+ stage: deploy
+ script: make deploy
+ environment:
+ name: production/$CI_COMMIT_REF_NAME
+ url: https://example.com/
+The result will then be:
+++Introduced in GitLab Premium 10.3.
+
With GitLab Premium, you can associate more than one Kubernetes clusters to your +project. That way you can have different clusters for different environments, +like dev, staging, production, etc.
+Simply add another cluster, like you did the first time, and make sure to +set an environment scope that will +differentiate the new cluster with the rest.
+The Kubernetes cluster integration exposes the following +deployment variables in the +GitLab CI/CD build environment.
+Variable | +Description | +
---|---|
KUBE_URL |
+Equal to the API URL. | +
KUBE_TOKEN |
+The Kubernetes token. | +
KUBE_NAMESPACE |
+The Kubernetes namespace is auto-generated if not specified. The default value is <project_name>-<project_id> . You can overwrite it to use different one if needed, otherwise the KUBE_NAMESPACE variable will receive the default value. |
+
KUBE_CA_PEM_FILE |
+Only present if a custom CA bundle was specified. Path to a file containing PEM data. | +
KUBE_CA_PEM |
+(deprecated) Only if a custom CA bundle was specified. Raw PEM data. | +
KUBECONFIG |
+Path to a file containing kubeconfig for this deployment. CA bundle would be embedded if specified. |
+
After you have successfully added your cluster information, you can enable the +Kubernetes cluster integration:
+You can now start using your Kubernetes cluster for your deployments.
+To disable the Kubernetes cluster integration, follow the same procedure.
+NOTE: Note: +You need Maintainer permissions and above to remove a Kubernetes cluster integration.
+NOTE: Note:
+When you remove a cluster, you only remove its relation to GitLab, not the
+cluster itself. To remove the cluster, you can do so by visiting the GKE
+dashboard or using kubectl
.
To remove the Kubernetes cluster integration from your project, simply click on the +Remove integration button. You will then be able to follow the procedure +and add a Kubernetes cluster again.
+Here's what you can do with GitLab if you enable the Kubernetes integration.
+++Available in GitLab Premium.
+
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.
+> Read more about Deploy Boards
+++Available in GitLab Premium.
+
Leverage Kubernetes' Canary deployments +and visualize your canary deployments right inside the Deploy Board, without +the need to leave GitLab.
+> Read more about Canary Deployments
+Automatically detect and monitor Kubernetes metrics. Automatic monitoring of +NGINX ingress is also supported.
+> Read more about Kubernetes monitoring
+Auto DevOps automatically detects, builds, tests, deploys, and monitors your +applications.
+To make full use of Auto DevOps(Auto Deploy, Auto Review Apps, and Auto Monitoring) +you will need the Kubernetes project integration enabled.
+ +NOTE: Note:
+Introduced in GitLab 8.15. You must be the project owner or have maintainer
permissions
+to use terminals. Support is limited to the first container in the
+first pod of your environment.
When enabled, the Kubernetes service adds web terminal
+support to your environments. This is based on the exec
functionality found in
+Docker and Kubernetes, so you get a new shell session within your existing
+containers. To use this integration, you should deploy to Kubernetes using
+the deployment variables above, ensuring any pods you create are labelled with
+app=$CI_ENVIRONMENT_SLUG
. GitLab will do the rest!
+Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
+++Note: +Not all of the GitLab-specific extensions to Markdown that are described in +this document currently work on our documentation website.
+For the best result, we encourage you to check this document out as rendered +by GitLab: markdown.md
+
GitLab uses (as of 11.1) the CommonMark Ruby Library for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. Previous content, wiki pages and Markdown files (.md
) in the repositories are still processed using the Redcarpet Ruby library.
Where there are significant differences, we will try to call them out in this document.
+GitLab uses "GitLab Flavored Markdown" (GFM). It extends the standard Markdown in a few significant ways to add some useful functionality. It was inspired by GitHub Flavored Markdown.
+You can use GFM in the following areas:
+.md
extension)You can also use other rich text files in GitLab. You might have to install a +dependency to do so. Please see the github-markup gem readme for more information.
+++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newlines
+
GFM honors the markdown specification in how paragraphs and line breaks are handled.
+A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. +Line-breaks, or soft returns, are rendered if you end a line with two or more spaces:
+Roses are red [followed by two or more spaces]
+Violets are blue
Sugar is sweet
+Roses are red
+Violets are blue
Sugar is sweet
+++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words
+
It is not reasonable to italicize just part of a word, especially when you're dealing with code and names that often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words:
+perform_complicated_task
+
+do_this_and_do_that_and_another_thing
+perform_complicated_task
+do_this_and_do_that_and_another_thing
+++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#url-auto-linking
+
GFM will autolink almost any URL you copy and paste into your text:
+* https://www.google.com
+* https://google.com/
+* ftp://ftp.us.debian.org/debian/
+* smb://foo/bar/baz
+* irc://irc.freenode.net/gitlab
+* http://localhost:3000
+++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote
+
On top of standard Markdown blockquotes, which require prepending >
to quoted lines,
+GFM supports multiline blockquotes fenced by >>>
:
>>>
+If you paste a message from somewhere else
+
+that
+
+spans
+
+multiple lines,
+
+you can quote that without having to manually prepend `>` to every line!
+>>>
+++If you paste a message from somewhere else
+that
+spans
+multiple lines,
+you can quote that without having to manually prepend
+>
to every line!
++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting
+
GitLab uses the Rouge Ruby library for syntax highlighting. For a +list of supported languages visit the Rouge website.
+Blocks of code are either fenced by lines with three back-ticks ```
,
+or are indented with four spaces. Only the fenced code blocks support syntax
+highlighting:
Inline `code` has `back-ticks around` it.
+Inline code
has back-ticks around
it.
Example:
+```javascript
+var s = "JavaScript syntax highlighting";
+alert(s);
+```
+
+```python
+def function():
+ #indenting works just fine in the fenced code block
+ s = "Python syntax highlighting"
+ print s
+```
+
+```ruby
+require 'redcarpet'
+markdown = Redcarpet.new("Hello World!")
+puts markdown.to_html
+```
+
+```
+No language indicated, so no syntax highlighting.
+s = "There is no highlighting for this."
+But let's throw in a <b>tag</b>.
+```
+becomes:
+var s = "JavaScript syntax highlighting";
+alert(s);
+def function():
+ #indenting works just fine in the fenced code block
+ s = "Python syntax highlighting"
+ print s
+require 'redcarpet'
+markdown = Redcarpet.new("Hello World!")
+puts markdown.to_html
+No language indicated, so no syntax highlighting.
+s = "There is no highlighting for this."
+But let's throw in a <b>tag</b>.
+++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff
+
With inline diffs tags you can display additions or deletions .
+The wrapping tags can be either curly braces or square brackets: additions or deletions .
+Examples:
+- {+ additions +}
+- [+ additions +]
+- {- deletions -}
+- [- deletions -]
+However the wrapping tags cannot be mixed as such:
+- {+ additions +]
+- [+ additions +}
+- {- deletions -]
+- [- deletions -}
+++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji
+
Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you:
+
+:zap: You can use emoji anywhere GFM is supported. :v:
+
+You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that.
+
+If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes.
+
+Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup:
+Sometimes you want to
You can use it to point out a
If you are new to this, don't be
Consult the Emoji Cheat Sheet for a list of all supported emoji codes.
GFM recognizes special references.
+You can easily reference e.g. an issue, a commit, a team member or even the whole team within a project.
+GFM will turn that reference into a link so you can navigate between them easily.
+GFM will recognize the following:
+input | +references | +
---|---|
@user_name |
+specific user | +
@group_name |
+specific group | +
@all |
+entire team | +
#12345 |
+issue | +
!123 |
+merge request | +
$123 |
+snippet | +
~123 |
+label by ID | +
~bug |
+one-word label by name | +
~"feature request" |
+multi-word label by name | +
%123 |
+project milestone by ID | +
%v1.23 |
+one-word milestone by name | +
%"release candidate" |
+multi-word milestone by name | +
9ba12248 |
+specific commit | +
9ba12248...b19a04f5 |
+commit range comparison | +
[README](doc/README) |
+repository file references | +
[README](doc/README#L13) |
+repository file line references | +
GFM also recognizes certain cross-project references:
+input | +references | +
---|---|
namespace/project#123 |
+issue | +
namespace/project!123 |
+merge request | +
namespace/project%123 |
+project milestone | +
namespace/project$123 |
+snippet | +
namespace/project@9ba12248 |
+specific commit | +
namespace/project@9ba12248...b19a04f5 |
+commit range comparison | +
namespace/project~"Some label" |
+issues with given label | +
It also has a shorthand version to reference other projects from the same namespace:
+input | +references | +
---|---|
project#123 |
+issue | +
project!123 |
+merge request | +
project%123 |
+project milestone | +
project$123 |
+snippet | +
project@9ba12248 |
+specific commit | +
project@9ba12248...b19a04f5 |
+commit range comparison | +
project~"Some label" |
+issues with given label | +
++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists
+
You can add task lists to issues, merge requests and comments. To create a task list, add a specially-formatted Markdown list, like so:
+- [x] Completed task
+- [ ] Incomplete task
+ - [ ] Sub-task 1
+ - [x] Sub-task 2
+ - [ ] Sub-task 3
+Tasks formatted as ordered lists are supported as well:
+1. [x] Completed task
+1. [ ] Incomplete task
+ 1. [ ] Sub-task 1
+ 1. [x] Sub-task 2
+Task lists can only be created in descriptions, not in titles. Task item state can be managed by editing the description's Markdown or by toggling the rendered check boxes.
+++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#videos
+
Image tags with a video extension are automatically converted to a video player.
+The valid video extensions are .mp4
, .m4v
, .mov
, .webm
, and .ogv
.
Here's a sample video:
+
+
+Here's a sample video:
+++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#math
+
It is possible to have math written with the LaTeX syntax rendered using KaTeX.
+Math written inside $``$
will be rendered inline with the text.
Math written inside triple back quotes, with the language declared as math
, will be rendered on a separate line.
Example:
+This math is inline $`a^2+b^2=c^2`$.
+
+This is on a separate line
+```math
+a^2+b^2=c^2
+```
+Becomes:
+This math is inline a^2+b^2=c^2
.
This is on a separate line
+a^2+b^2=c^2
+Be advised that KaTeX only supports a subset of LaTeX.
+++Note: +This also works for the asciidoctor
+:stem: latexmath
. For details see the asciidoctor user manual.
++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#colors
+
It is possible to have color written in HEX, RGB or HSL format rendered with a color indicator.
+Color written inside backticks will be followed by a color "chip".
+Examples:
+`#F00`
+`#F00A`
+`#FF0000`
+`#FF0000AA`
+`RGB(0,255,0)`
+`RGB(0%,100%,0%)`
+`RGBA(0,255,0,0.7)`
+`HSL(540,70%,50%)`
+`HSLA(540,70%,50%,0.7)`
+Become:
+#F00
+#F00A
+#FF0000
+#FF0000AA
+RGB(0,255,0)
+RGB(0%,100%,0%)
+RGBA(0,255,0,0.7)
+HSL(540,70%,50%)
+HSLA(540,70%,50%,0.7)
`#RGB[A]`
or `#RRGGBB[AA]`
+`RGB[A](R, G, B[, A])`
+`HSL[A](H, S, L[, A])`
+++Introduced in +GitLab 10.3.
+
++If this is not rendered correctly, see +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#mermaid
+
It is possible to generate diagrams and flowcharts from text using Mermaid.
+In order to generate a diagram or flowchart, you should write your text inside the mermaid
block.
Example:
+```mermaid
+graph TD;
+ A-->B;
+ A-->C;
+ B-->D;
+ C-->D;
+```
+Becomes:
+graph TD;
+ A-->B;
+ A-->C;
+ B-->D;
+ C-->D;
+For details see the Mermaid official page.
+# H1
+## H2
+### H3
+#### H4
+##### H5
+###### H6
+
+Alternatively, for H1 and H2, an underline-ish style:
+
+Alt-H1
+======
+
+Alt-H2
+------
+All Markdown-rendered headers automatically get IDs, except in comments.
+On hover, a link to those IDs becomes visible to make it easier to copy the link to the header to give it to someone else.
+The IDs are generated from the content of the header according to the following rules:
+For example:
+# This header has spaces in it
+## This header has a :thumbsup: in it
+# This header has Unicode in it: 한글
+## This header has spaces in it
+### This header has spaces in it
+## This header has 3.5 in it (and parentheses)
+Would generate the following link IDs:
+this-header-has-spaces-in-it
this-header-has-a-in-it
this-header-has-unicode-in-it-한글
this-header-has-spaces-in-it
this-header-has-spaces-in-it-1
this-header-has-3-5-in-it-and-parentheses
Note that the Emoji processing happens before the header IDs are generated, so the Emoji is converted to an image which then gets removed from the ID.
+Examples:
+Emphasis, aka italics, with *asterisks* or _underscores_.
+
+Strong emphasis, aka bold, with **asterisks** or __underscores__.
+
+Combined emphasis with **asterisks and _underscores_**.
+
+Strikethrough uses two tildes. ~~Scratch this.~~
+Become:
+Emphasis, aka italics, with asterisks or underscores.
+Strong emphasis, aka bold, with asterisks or underscores.
+Combined emphasis with asterisks and underscores.
+Strikethrough uses two tildes. Scratch this.
Examples:
+1. First ordered list item
+2. Another item
+ * Unordered sub-list.
+1. Actual numbers don't matter, just that it's a number
+ 1. Ordered sub-list
+4. And another item.
+
+* Unordered list can use asterisks
+- Or minuses
++ Or pluses
+Become:
+If a list item contains multiple paragraphs, +each subsequent paragraph should be indented to the same level as the start of the list item text (Redcarpet: paragraph should be indented with four spaces.)
+Example:
+1. First ordered list item
+
+ Second paragraph of first item.
+
+2. Another item
+Becomes:
+First ordered list item
+Paragraph of first item.
+Another item
+If the paragraph of the first item is not indented with the proper number of spaces, +the paragraph will appear outside the list, instead of properly indented under the list item.
+Example:
+1. First ordered list item
+
+ Paragraph of first item.
+
+2. Another item
+Becomes:
+Paragraph of first item.
+There are two ways to create links, inline-style and reference-style.
+[I'm an inline-style link](https://www.google.com)
+
+[I'm a reference-style link][Arbitrary case-insensitive reference text]
+
+[I'm a relative reference to a repository file](LICENSE)
+
+[I am an absolute reference within the repository](/doc/user/markdown.md)
+
+[I link to the Milestones page](/../milestones)
+
+[You can use numbers for reference-style link definitions][1]
+
+Or leave it empty and use the [link text itself][]
+
+Some text to show that the reference links can follow later.
+
+[arbitrary case-insensitive reference text]: https://www.mozilla.org
+[1]: http://slashdot.org
+[link text itself]: https://www.reddit.com
+++Note: +Relative links do not allow referencing project files in a wiki page or wiki +page in a project file. The reason for this is that, in GitLab, wiki is always +a separate Git repository. For example,
+[I'm a reference-style link](style)
+will point the link towikis/style
when the link is inside of a wiki markdown file.
Examples:
+Here's our logo (hover to see the title text):
+
+Inline-style:
+
+
+Reference-style:
+![alt text1][logo]
+
+[logo]: img/markdown_logo.png
+Become:
+Here's our logo:
+Inline-style:
+ +Reference-style:
+ +Examples:
+> Blockquotes are very handy in email to emulate reply text.
+> This line is part of the same quote.
+
+Quote break.
+
+> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.
+Become:
+++Blockquotes are very handy in email to emulate reply text. +This line is part of the same quote.
+
Quote break.
+++This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can put Markdown into a blockquote.
+
You can also use raw HTML in your Markdown, and it'll mostly work pretty well.
+See the documentation for HTML::Pipeline's SanitizationFilter class for the list of allowed HTML tags and attributes. In addition to the default SanitizationFilter
whitelist, GitLab allows span
, abbr
, details
and summary
elements.
Examples:
+<dl>
+ <dt>Definition list</dt>
+ <dd>Is something people use sometimes.</dd>
+
+ <dt>Markdown in HTML</dt>
+ <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
+</dl>
+Become:
+Content can be collapsed using HTML's <details>
and <summary>
tags. This is especially useful for collapsing long logs so they take up less screen space.
+ These details will remain hidden until expanded.Click me to collapse/fold.
+
+PASTE LOGS HERE
Note: Markdown inside these tags is supported, as long as you have a blank link after the </summary>
tag and before the </details>
tag, as shown in the example. Redcarpet does not support Markdown inside these tags. You can work around this by using HTML, for example you can use <pre><code>
tags instead of code fences.
<details>
+<summary>Click me to collapse/fold.</summary>
+
+These details _will_ remain **hidden** until expanded.
+
+ PASTE LOGS HERE
+
+</details>
+Examples:
+Three or more...
+
+---
+
+Hyphens
+
+***
+
+Asterisks
+
+___
+
+Underscores
+Become:
+Three or more...
+Hyphens
+Asterisks
+Underscores
+A good way to learn how line breaks work is to experiment and discover -- hit Enter once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want. The "Preview" tab is your friend.
+Here are some things to try out:
+Examples:
+Here's a line for us to start with.
+
+This line is separated from the one above by two newlines, so it will be a *separate paragraph*.
+
+This line is also a separate paragraph, but...
+This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*.
+
+This line is also a separate paragraph, and...
+This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*)
+
+spaces.
+Become:
+Here's a line for us to start with.
+This line is separated from the one above by two newlines, so it will be a separate paragraph.
+This line is also a separate paragraph, but... +This line is only separated by a single newline, so it does not break and just follows the previous line in the same paragraph.
+This line is also a separate paragraph, and...
+This line is on its own line, because the previous line ends with two spaces. (but still in the same paragraph)
spaces.
+Tables aren't part of the core Markdown spec, but they are part of GFM.
+Example:
+| header 1 | header 2 |
+| -------- | -------- |
+| cell 1 | cell 2 |
+| cell 3 | cell 4 |
+Becomes:
+header 1 | +header 2 | +
---|---|
cell 1 | +cell 2 | +
cell 3 | +cell 4 | +
Note: The row of dashes between the table header and body must have at least three dashes in each column.
+By including colons in the header row, you can align the text within that column.
+Example:
+| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned |
+| :----------- | :------: | ------------: | :----------- | :------: | ------------: |
+| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 |
+| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 |
+Becomes:
+Left Aligned | +Centered | +Right Aligned | +Left Aligned | +Centered | +Right Aligned | +
---|---|---|---|---|---|
Cell 1 | +Cell 2 | +Cell 3 | +Cell 4 | +Cell 5 | +Cell 6 | +
Cell 7 | +Cell 8 | +Cell 9 | +Cell 10 | +Cell 11 | +Cell 12 | +
Example:
+You can add footnotes to your text as follows.[^2]
+[^2]: This is my awesome footnote.
+Becomes:
+You can add footnotes to your text as follows.[1]
+CommonMark and GFM currently do not support the superscript syntax ( x^2
) that Redcarpet does. You can use the standard HTML syntax for superscripts and subscripts.
The formula for water is H<sub>2</sub>O
+while the equation for the theory of relativity is E = mc<sup>2</sup>.
+The formula for water is H2O while the equation for the theory of relativity is E = mc2.
+The following examples show how links inside wikis behave.
+A link which just includes the slug for a page will point to that page, +at the base level of the wiki.
+This snippet would link to a documentation
page at the root of your wiki:
[Link to Documentation](documentation)
+Links with a file extension point to that file, relative to the current page.
+If this snippet was placed on a page at <your_wiki>/documentation/related
,
+it would link to <your_wiki>/documentation/file.md
:
[Link to File](file.md)
+A link can be constructed relative to the current wiki page using ./<page>
,
+../<page>
, etc.
If this snippet was placed on a page at <your_wiki>/documentation/main
,
+it would link to <your_wiki>/documentation/related
:
[Link to Related Page](./related)
+If this snippet was placed on a page at <your_wiki>/documentation/related/content
,
+it would link to <your_wiki>/documentation/main
:
[Link to Related Page](../main)
+If this snippet was placed on a page at <your_wiki>/documentation/main
,
+it would link to <your_wiki>/documentation/related.md
:
[Link to Related Page](./related.md)
+If this snippet was placed on a page at <your_wiki>/documentation/related/content
,
+it would link to <your_wiki>/documentation/main.md
:
[Link to Related Page](../main.md)
+A link starting with a /
is relative to the wiki root.
This snippet links to <wiki_root>/documentation
:
[Link to Related Page](/documentation)
+This snippet links to <wiki_root>/miscellaneous.md
:
[Link to Related Page](/miscellaneous.md)
+This is my awesome footnote.
+Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+
+GitLab is open source software to collaborate on code.
+
+Manage git repositories with fine-grained access controls that keep your code secure.
+
+Perform code reviews and enhance collaboration with merge requests.
+
+Each project can also have an issue tracker and a wiki.
+
+Used by more than 100,000 organizations, GitLab is the most popular solution to manage git repositories on-premises.
+
+Read more about GitLab at about.gitlab.com.
+
Check the current instance configuration
+ +Welcome to GitLab, a Git-based fully featured +platform for software development!
+GitLab offers the most scalable Git-based fully integrated platform for +software development, with flexible products and subscriptions. +To understand what features you have access to, check the GitLab subscriptions below.
+Shortcuts to GitLab's most visited docs:
+General documentation | +GitLab CI/CD docs | +
---|---|
User documentation | +GitLab CI/CD quick start guide | +
Administrator documentation | +GitLab CI/CD examples | +
Contributor documentation | +Configuring .gitlab-ci.yml |
+
Getting started with GitLab | +Using Docker images | +
API | +Auto DevOps | +
SSH authentication | +Kubernetes integration | +
GitLab Pages | +GitLab Container Registry | +
GitLab is the first single application for software development, security, +and operations that enables Concurrent DevOps, making the software lifecycle +three times faster and radically improving the speed of business. GitLab +provides solutions for all the stages of the DevOps lifecycle: +plan, create, verify, package, +release, configure, monitor.
+ +Whether you use Waterfall, Agile, or Conversational Development, +GitLab streamlines your collaborative workflows. Visualize, prioritize, +coordinate, and track your progress your way with GitLab’s flexible project +management tools.
+Consolidate source code into a single DVCS +that’s easily managed and controlled without disrupting your workflow. +GitLab’s git repositories come complete with branching tools and access +controls, providing a scalable, single source of truth for collaborating +on projects and code.
+Manage your repositories from the UI (user interface):
+Spot errors sooner, improve security and shorten feedback cycles with built-in +static code analysis, code testing, code quality, dependency checking and review +apps. Customize your approval workflow controls, automatically test the quality +of your code, and spin up a staging environment for every code change. GitLab +Continuous Integration is the most popular next generation testing system that +scales to run your tests faster.
+GitLab Container Registry gives you the enhanced security and access controls of +custom Docker images without 3rd party add-ons. Easily upload and download images +from GitLab CI/CD with full Git repository management integration.
+Spend less time configuring your tools, and more time creating. Whether you’re +deploying to one server or thousands, build, test, and release your code +confidently and securely with GitLab’s built-in Continuous Delivery and Deployment.
+Automate your entire workflow from build to deploy and monitoring with GitLab +Auto Devops. Best practice templates get you started with minimal to zero +configuration. Then customize everything from buildpacks to CI/CD.
+Measure how long it takes to go from planning to monitoring and ensure your +applications are always responsive and available. GitLab collects and displays +performance metrics for deployed apps using Prometheus so you can know in an +instant how code changes impact your production environment.
+Administration documentation applies to admin users of GitLab +self-hosted instances.
+Learn how to install, configure, update, upgrade, integrate, and maintain your own instance. +Regular users don't have access to GitLab administration tools and settings.
+GitLab Community Edition is open source +and GitLab Enterprise Edition is open-core. +Learn how to contribute to GitLab:
+You have two options to use GitLab:
+With GitLab self-hosted, you deploy your own GitLab instance on-premises or on a private cloud of your choice. GitLab self-hosted is available for free and with paid subscriptions: Core, Starter, Premium, and Ultimate.
+Every feature available in Core is also available in Starter, Premium, and Ultimate. +Starter features are also available in Premium and Ultimate, and Premium features are also +available in Ultimate.
+GitLab.com is hosted, managed, and administered by GitLab, Inc., with +free and paid subscriptions for individuals +and teams: Free, Bronze, Silver, and Gold.
+GitLab.com subscriptions grants access +to the same features available in GitLab self-hosted, except +administration tools and settings:
+For supporting the open source community and encouraging the development of +open source projects, GitLab grants access to Gold features +for all GitLab.com public projects, regardless of the subscription.
+To know more about GitLab subscriptions and licensing, please refer to the +GitLab Product Marketing Handbook.
+In GitLab, you can create projects for hosting +your codebase, use it as an issue tracker, collaborate on code, and continuously +build, test, and deploy your app with built-in GitLab CI/CD.
+Your projects can be available +publicly, internally, or privately, at your choice. GitLab does not limit +the number of private projects you create.
+When you create a project in GitLab, you'll have access to a large number of +features:
+Issues and merge requests:
+GitLab CI/CD:
+.gitlab-ci.yml
, test coverage parsing, pipeline's visibility, and much moreOther features:
+Integrate your project with Jira, Mattermost, +Kubernetes, Slack, and a lot more.
+Learn how to create a new project in GitLab.
+You can fork a project in order to:
+Set the project's visibility level and the access levels to its various pages +and perform actions like archiving, renaming or transferring a project.
+Read through the documentation on project settings.
+Learn how to add members to your projects.
+Leave project will only display on the project's dashboard +when a project is part of a group (under a +group namespace). +If you choose to leave a project you will no longer be a project +member, therefore, unable to contribute.
+When a repository path changes, it is essential to smoothly transition from the +old location to the new one. GitLab provides two kinds of redirects: the web UI +and Git push/pull redirects.
+Depending on the situation, different things apply.
+When renaming a user, +changing a group path or renaming a repository:
+Automate GitLab via a simple and powerful API. All definitions can be found
+under /lib/api
.
Documentation for various API resources can be found separately in the +following locations:
+Going forward, we will start on moving to +GraphQL and deprecate the use of +controller-specific endpoints. GraphQL has a number of benefits:
+It will co-exist with the current v4 REST API. If we have a v5 API, this should +be a compatibility layer on top of GraphQL.
+Although there were some patenting and licensing concerns with GraphQL, these +have been resolved to our satisfaction by the relicensing of the reference +implementations under MIT, and the use of the OWF license for the GraphQL +specification.
+The HTTP API is versioned using a single number, the current one being 4. This +number symbolises the same as the major version number as described by +SemVer. This mean that backward incompatible changes +will require this version number to change. However, the minor version is +not explicit. This allows for a stable API endpoint, but also means new +features can be added to the API in the same version number.
+New features and bug fixes are released in tandem with a new GitLab, and apart +from incidental patch and security releases, are released on the 22nd each +month. Backward incompatible changes (e.g. endpoints removal, parameters +removal etc.), as well as removal of entire API versions are done in tandem +with a major point release of GitLab itself. All deprecations and changes +between two versions should be listed in the documentation. For the changes +between v3 and v4; please read the v3 to v4 documentation
+Currently only API version v4 is available. Version v3 was removed in +GitLab 11.0.
+API requests should be prefixed with api
and the API version. The API version
+is defined in lib/api.rb
. For example, the root of the v4 API
+is at /api/v4
.
Example of a valid API request using cURL:
+curl "https://gitlab.example.com/api/v4/projects"
+The API uses JSON to serialize data. You don't need to specify .json
at the
+end of an API URL.
Most API requests require authentication, or will only return public data when
+authentication is not provided. For
+those cases where it is not required, this will be mentioned in the documentation
+for each individual endpoint. For example, the /projects/:id
endpoint.
There are three ways to authenticate with the GitLab API:
+ +For admins who want to authenticate with the API as a specific user, or who want to build applications or scripts that do so, two options are available:
+ +If authentication information is invalid or omitted, an error message will be
+returned with status code 401
:
{
+ "message": "401 Unauthorized"
+}
+You can use an OAuth2 token to authenticate with the API by passing it in either the
+access_token
parameter or the Authorization
header.
Example of using the OAuth2 token in a parameter:
+curl https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN
+Example of using the OAuth2 token in a header:
+curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v4/projects
+Read more about GitLab as an OAuth2 provider.
+You can use a personal access token to authenticate with the API by passing it in either the
+private_token
parameter or the Private-Token
header.
Example of using the personal access token in a parameter:
+curl https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK
+Example of using the personal access token in a header:
+curl --header "Private-Token: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects
+Read more about personal access tokens.
+When signing in to the main GitLab application, a _gitlab_session
cookie is
+set. The API will use this cookie for authentication if it is present, but using
+the API to generate a new session cookie is currently not supported.
The primary user of this authentication method is the web frontend of GitLab itself, +which can use the API as the authenticated user to get a list of their projects, +for example, without needing to explicitly pass an access token.
+++Introduced in GitLab 9.0. Needs admin permissions.
+
Impersonation tokens are a type of personal access token +that can only be created by an admin for a specific user. They are a great fit +if you want to build applications or scripts that authenticate with the API as a specific user.
+They are an alternative to directly using the user's password or one of their +personal access tokens, and to using the Sudo feature, since the user's (or admin's, in the case of Sudo) +password/token may not be known or may change over time.
+For more information, refer to the +users API docs.
+Impersonation tokens are used exactly like regular personal access tokens, and can be passed in either the
+private_token
parameter or the Private-Token
header.
++Needs admin permissions.
+
All API requests support performing an API call as if you were another user,
+provided you are authenticated as an administrator with an OAuth or Personal Access Token that has the sudo
scope.
You need to pass the sudo
parameter either via query string or a header with an ID/username of
+the user you want to perform the operation as. If passed as a header, the
+header name must be Sudo
.
If a non administrative access token is provided, an error message will
+be returned with status code 403
:
{
+ "message": "403 Forbidden - Must be admin to use sudo"
+}
+If an access token without the sudo
scope is provided, an error message will
+be returned with status code 403
:
{
+ "error": "insufficient_scope",
+ "error_description": "The request requires higher privileges than provided by the access token.",
+ "scope": "sudo"
+}
+If the sudo user ID or username cannot be found, an error message will be
+returned with status code 404
:
{
+ "message": "404 User with ID or username '123' Not Found"
+}
+Example of a valid API call and a request using cURL with sudo request, +providing a username:
+GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username
+curl --header "Private-Token: 9koXpg98eAheJpvBs5tK" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects"
+Example of a valid API call and a request using cURL with sudo request, +providing an ID:
+GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
+curl --header "Private-Token: 9koXpg98eAheJpvBs5tK" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects"
+The API is designed to return different status codes according to context and +action. This way, if a request results in an error, the caller is able to get +insight into what went wrong.
+The following table gives an overview of how the API functions generally behave.
+Request type | +Description | +
---|---|
GET |
+Access one or more resources and return the result as JSON. | +
POST |
+Return 201 Created if the resource is successfully created and return the newly created resource as JSON. |
+
+GET / PUT
+ |
+Return 200 OK if the resource is accessed or modified successfully. The (modified) result is returned as JSON. |
+
DELETE |
+Returns 204 No Content if the resource was deleted successfully. |
+
The following table shows the possible return codes for API requests.
+Return values | +Description | +
---|---|
200 OK |
+The GET , PUT or DELETE request was successful, the resource(s) itself is returned as JSON. |
+
204 No Content |
+The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. | +
201 Created |
+The POST request was successful and the resource is returned as JSON. |
+
304 Not Modified |
+Indicates that the resource has not been modified since the last request. | +
400 Bad Request |
+A required attribute of the API request is missing, e.g., the title of an issue is not given. | +
401 Unauthorized |
+The user is not authenticated, a valid user token is necessary. | +
403 Forbidden |
+The request is not allowed, e.g., the user is not allowed to delete a project. | +
404 Not Found |
+A resource could not be accessed, e.g., an ID for a resource could not be found. | +
405 Method Not Allowed |
+The request is not supported. | +
409 Conflict |
+A conflicting resource already exists, e.g., creating a project with a name that already exists. | +
412 |
+Indicates the request was denied. May happen if the If-Unmodified-Since header is provided when trying to delete a resource, which was modified in between. |
+
422 Unprocessable |
+The entity could not be processed. | +
500 Server Error |
+While handling the request something went wrong server-side. | +
Sometimes the returned result will span across many pages. When listing +resources you can pass the following parameters:
+Parameter | +Description | +
---|---|
page |
+Page number (default: 1 ) |
+
per_page |
+Number of items to list per page (default: 20 , max: 100 ) |
+
In the example below, we list 50 namespaces per page.
+curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/namespaces?per_page=50
+Link headers are sent back with each
+response. They have rel
set to prev/next/first/last and contain the relevant
+URL. Please use these links instead of generating your own URLs.
In the cURL example below, we limit the output to 3 items per page (per_page=3
)
+and we request the second page (page=2
) of comments of the issue
+with ID 8
which belongs to the project with ID 8
:
curl --head --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/8/issues/8/notes?per_page=3&page=2
+The response will then be:
+HTTP/1.1 200 OK
+Cache-Control: no-cache
+Content-Length: 1103
+Content-Type: application/json
+Date: Mon, 18 Jan 2016 09:43:18 GMT
+Link: <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last"
+Status: 200 OK
+Vary: Origin
+X-Next-Page: 3
+X-Page: 2
+X-Per-Page: 3
+X-Prev-Page: 1
+X-Request-Id: 732ad4ee-9870-4866-a199-a9db0cde3c86
+X-Runtime: 0.108688
+X-Total: 8
+X-Total-Pages: 3
+Additional pagination headers are also sent back.
+Header | +Description | +
---|---|
X-Total |
+The total number of items | +
X-Total-Pages |
+The total number of pages | +
X-Per-Page |
+The number of items per page | +
X-Page |
+The index of the current page (starting at 1) | +
X-Next-Page |
+The index of the next page | +
X-Prev-Page |
+The index of the previous page | +
If using namespaced API calls, make sure that the NAMESPACE/PROJECT_NAME
is
+URL-encoded.
For example, /
is represented by %2F
:
GET /api/v4/projects/diaspora%2Fdiaspora
+If your branch or tag contains a /
, make sure the branch/tag name is
+URL-encoded.
For example, /
is represented by %2F
:
GET /api/v4/projects/1/branches/my%2Fbranch/commits
+id
vs iid
+When you work with the API, you may notice two similar fields in API entities:
+id
and iid
. The main difference between them is scope.
For example, an issue might have id: 46
and iid: 5
.
Parameter | +Description | +
---|---|
id |
+Is unique across all issues and is used for any API call | +
iid |
+Is unique only in scope of a single project. When you browse issues or merge requests with the Web UI, you see the iid
+ |
+
That means that if you want to get an issue via the API you should use the id
:
GET /projects/42/issues/:id
+On the other hand, if you want to create a link to a web page you should use
+the iid
:
GET /projects/42/issues/:iid
+When working with the API you may encounter validation errors, in which case
+the API will answer with an HTTP 400
status.
Such errors appear in two cases:
+When an attribute is missing, you will get something like:
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+{
+ "message":"400 (Bad request) \"title\" not given"
+}
+When a validation error occurs, error messages will be different. They will +hold all details of validation errors:
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+{
+ "message": {
+ "bio": [
+ "is too long (maximum is 255 characters)"
+ ]
+ }
+}
+This makes error messages more machine-readable. The format can be described as +follows:
+{
+ "message": {
+ "<property-name>": [
+ "<error-message>",
+ "<error-message>",
+ ...
+ ],
+ "<embed-entity>": {
+ "<property-name>": [
+ "<error-message>",
+ "<error-message>",
+ ...
+ ],
+ }
+ }
+}
+When you try to access an API URL that does not exist you will receive 404 Not Found.
+HTTP/1.1 404 Not Found
+Content-Type: application/json
+{
+ "error": "404 Not Found"
+}
++
in ISO 8601 datesIf you need to include a +
in a query parameter, you may need to use %2B
instead due
+a W3 recommendation that
+causes a +
to be interpreted as a space. For example, in an ISO 8601 date, you may want to pass
+a time in Mountain Standard Time, such as:
2017-10-17T23:11:13.000+05:30
+The correct encoding for the query parameter would be:
+2017-10-17T23:11:13.000%2B05:30
+There are many unofficial GitLab API Clients for most of the popular +programming languages. Visit the GitLab website for a complete list.
++Discover projects, groups and snippets. Share your projects with others +
++Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
+++Introduced in GitLab 10.0. Generally available on GitLab 11.0.
+
Auto DevOps automatically detects, builds, tests, deploys, and monitors your +applications.
+With Auto DevOps, the software development process becomes easier to set up +as every project can have a complete workflow from verification to monitoring +without needing to configure anything. Just push your code and GitLab takes +care of everything else. This makes it easier to start new projects and brings +consistency to how applications are set up throughout a company.
+If you are using GitLab.com, see the quick start guide +for using Auto DevOps with GitLab.com and a Kubernetes cluster on Google Kubernetes +Engine.
+Auto DevOps provides functionality described by others as an application +platform or as a Platform as a Service (PaaS). It takes inspiration from the +innovative work done by Heroku and goes beyond it +in a couple of ways:
+Comprised of a set of stages, Auto DevOps brings these best practices to your +project in a simple and automatic way:
+As Auto DevOps relies on many different components, it's good to have a basic +knowledge of the following:
+Auto DevOps provides great defaults for all the stages; you can, however, +customize almost everything to your needs.
+For an overview on the creation of Auto DevOps, read the blog post From 2/3 of the Self-Hosted Git Market, to the Next-Generation CI System, to Auto DevOps.
+TIP: Tip: +For self-hosted installations, the easiest way to make use of Auto DevOps is to +install GitLab inside a Kubernetes cluster using the GitLab Omnibus Helm Chart +which automatically installs and configures everything you need!
+To make full use of Auto DevOps, you will need:
+nginx-ingress
+Helm chart.kube-lego
+Helm chart to your Kubernetes cluster to automatically issue certificates
+for your domains using Let's Encrypt.NOTE: Note: +If you do not have Kubernetes or Prometheus installed, then Auto Review Apps, +Auto Deploy, and Auto Monitoring will be silently skipped.
+The Auto DevOps base domain is required if you want to make use of Auto +Review Apps and Auto Deploy. It can be defined +in three places:
+AUTO_DEVOPS_DOMAIN
(required if you want to use multiple clusters)A wildcard DNS A record matching the base domain(s) is required, for example,
+given a base domain of example.com
, you'd need a DNS entry like:
*.example.com 3600 A 1.2.3.4
+In this case, example.com
is the domain name under which the deployed apps will be served,
+and 1.2.3.4
is the IP address of your load balancer; generally NGINX
+(see requirements). How to set up the DNS record is beyond
+the scope of this document; you should check with your DNS provider.
Alternatively you can use free public services like nip.io
+which provide automatic wildcard DNS without any configuration. Just set the
+Auto DevOps base domain to 1.2.3.4.nip.io
.
Once set up, all requests will hit the load balancer, which in turn will route +them to the Kubernetes pods that run your application(s).
+NOTE: Note: +If GitLab is installed using the GitLab Omnibus Helm Chart, there are two +options: provide a static IP, or have one assigned. For more information see the +relevant docs on the network prerequisites.
+When using Auto DevOps, you may want to deploy different environments to +different Kubernetes clusters. This is possible due to the 1:1 connection that +exists between them.
+In the Auto DevOps template +(used behind the scenes by Auto DevOps), there are currently 3 defined environment names that you need to know:
+review/
(every environment starting with review/
)staging
production
Those environments are tied to jobs that use Auto Deploy, so
+except for the environment scope, they would also need to have a different
+domain they would be deployed to. This is why you need to define a separate
+AUTO_DEVOPS_DOMAIN
variable for all the above
+based on the environment.
The following table is an example of how the three different clusters would +be configured.
+Cluster name | +Cluster environment scope | +
+AUTO_DEVOPS_DOMAIN variable value |
+Variable environment scope | +Notes | +
---|---|---|---|---|
review | +review/* |
+review.example.com |
+review/* |
+The review cluster which will run all Review Apps. * is a wildcard, which means it will be used by every environment name starting with review/ . |
+
staging | +staging |
+staging.example.com |
+staging |
+(Optional) The staging cluster which will run the deployments of the staging environments. You need to enable it first. | +
production | +production |
+example.com |
+production |
+The production cluster which will run the deployments of the production environment. You can use incremental rollouts. | +
To add a different cluster for each environment:
+Navigate to your project's Operations > Kubernetes and create the Kubernetes clusters +with their respective environment scope as described from the table above.
+ +After the clusters are created, navigate to each one and install Helm Tiller +and Ingress.
+Make sure you have configured your DNS with the +specified Auto DevOps domains.
+Navigate to your project's Settings > CI/CD > Variables and add
+the AUTO_DEVOPS_DOMAIN
variables with their respective environment
+scope.
Now that all is configured, you can test your setup by creating a merge request
+and verifying that your app is deployed as a review app in the Kubernetes
+cluster with the review/*
environment scope. Similarly, you can check the
+other environments.
If you haven't done already, read the requirements to make +full use of Auto DevOps. If this is your fist time, we recommend you follow the +quick start guide.
+To enable Auto DevOps to your project:
+.gitlab-ci.yml
, or remove it otherwiseOnce saved, an Auto DevOps pipeline will be triggered on the default branch.
+NOTE: Note:
+For GitLab versions 10.0 - 10.2, when enabling Auto DevOps, a pipeline needs to be
+manually triggered either by pushing a new commit to the repository or by visiting
+https://example.gitlab.com/<username>/<project>/pipelines/new
and creating
+a new pipeline for your default branch, generally master
.
NOTE: Note: +If you are a GitLab Administrator, you can enable Auto DevOps instance wide +in Admin Area > Settings > Continuous Integration and Deployment. Doing that, +all the projects that haven't explicitly set an option will have Auto DevOps +enabled by default.
+++Introduced in GitLab 11.0.
+
You can change the deployment strategy used by Auto DevOps by going to your +project's Settings > CI/CD > Auto DevOps.
+The available options are:
+STAGING_ENABLED
and
+INCREMENTAL_ROLLOUT_ENABLED
variables
+to false.STAGING_ENABLED
and
+INCREMENTAL_ROLLOUT_ENABLED
variables
+to true, and the user is responsible for manually deploying to staging and production.The following sections describe the stages of Auto DevOps. Read them carefully +to understand how each one works.
+Auto Build creates a build of the application in one of two ways:
+Dockerfile
, it will use docker build
to create a Docker image.Either way, the resulting Docker image is automatically pushed to the +Container Registry and tagged with the commit SHA.
+CAUTION: Important:
+If you are also using Auto Review Apps and Auto Deploy and choose to provide
+your own Dockerfile
, make sure you expose your application to port
+5000
as this is the port assumed by the default Helm chart.
Auto Test automatically runs the appropriate tests for your application using +Herokuish and Heroku +buildpacks by analyzing +your project to detect the language and framework. Several languages and +frameworks are detected automatically, but if your language is not detected, +you may succeed with a custom buildpack. Check the +currently supported languages.
+NOTE: Note: +Auto Test uses tests you already have in your application. If there are no +tests, it's up to you to add them.
+Auto Code Quality uses the +Code Quality image to run +static analysis and other code checks on the current code. The report is +created, and is uploaded as an artifact which you can later download and check +out.
+In GitLab Starter, differences between the source and +target branches are also +shown in the merge request widget.
+++Introduced in GitLab Ultimate 10.3.
+
Static Application Security Testing (SAST) uses the +SAST Docker image to run static +analysis on the current code and checks for potential security issues. Once the +report is created, it's uploaded as an artifact which you can later download and +check out.
+In GitLab Ultimate, any security warnings are also +shown in the merge request widget.
+++Introduced in GitLab Ultimate 10.7.
+
Dependency Scanning uses the +Dependency Scanning Docker image +to run analysis on the project dependencies and checks for potential security issues. Once the +report is created, it's uploaded as an artifact which you can later download and +check out.
+Any security warnings are also +shown in the merge request widget.
+++Introduced in GitLab Ultimate 11.0.
+
License Management uses the +License Management Docker image +to search the project dependencies for their license. Once the +report is created, it's uploaded as an artifact which you can later download and +check out.
+Any licenses are also +shown in the merge request widget.
+++Introduced in GitLab 10.4.
+
Vulnerability Static Analysis for containers uses +Clair to run static analysis on a +Docker image and checks for potential security issues. Once the report is +created, it's uploaded as an artifact which you can later download and +check out.
+In GitLab Ultimate, any security warnings are also +shown in the merge request widget.
+NOTE: Note: +This is an optional step, since many projects do not have a Kubernetes cluster +available. If the requirements are not met, the job will +silently be skipped.
+CAUTION: Caution: +Your apps should not be manipulated outside of Helm (using Kubernetes directly.) +This can cause confusion with Helm not detecting the change, and subsequent +deploys with Auto DevOps can undo your changes. Also, if you change something +and want to undo it by deploying again, Helm may not detect that anything changed +in the first place, and thus not realize that it needs to re-apply the old config.
+Review Apps are temporary application environments based on the +branch's code so developers, designers, QA, product managers, and other +reviewers can actually see and interact with code changes as part of the review +process. Auto Review Apps create a Review App for each branch.
+The Review App will have a unique URL based on the project name, the branch
+name, and a unique number, combined with the Auto DevOps base domain. For
+example, user-project-branch-1234.example.com
. A link to the Review App shows
+up in the merge request widget for easy discovery. When the branch is deleted,
+for example after the merge request is merged, the Review App will automatically
+be deleted.
++Introduced in GitLab Ultimate 10.4.
+
Dynamic Application Security Testing (DAST) uses the +popular open source tool OWASP ZAProxy +to perform an analysis on the current code and checks for potential security +issues. Once the report is created, it's uploaded as an artifact which you can +later download and check out.
+In GitLab Ultimate, any security warnings are also +shown in the merge request widget.
+++Introduced in GitLab Premium 10.4.
+
Auto Browser Performance Testing utilizes the Sitespeed.io container to measure the performance of a web page. A JSON report is created and uploaded as an artifact, which includes the overall performance score for each page. By default, the root page of Review and Production environments will be tested. If you would like to add additional URL's to test, simply add the paths to a file named .gitlab-urls.txt
in the root directory, one per line. For example:
/
+/features
+/direction
+In GitLab Premium, performance differences between the source +and target branches are shown in the merge request widget.
+NOTE: Note: +This is an optional step, since many projects do not have a Kubernetes cluster +available. If the requirements are not met, the job will +silently be skipped.
+CAUTION: Caution: +Your apps should not be manipulated outside of Helm (using Kubernetes directly.) +This can cause confusion with Helm not detecting the change, and subsequent +deploys with Auto DevOps can undo your changes. Also, if you change something +and want to undo it by deploying again, Helm may not detect that anything changed +in the first place, and thus not realize that it needs to re-apply the old config.
+After a branch or merge request is merged into the project's default branch (usually
+master
), Auto Deploy deploys the application to a production
environment in
+the Kubernetes cluster, with a namespace based on the project name and unique
+project ID, for example project-4321
.
Auto Deploy doesn't include deployments to staging or canary by default, but the +Auto DevOps template contains job definitions for these tasks if you want to +enable them.
+You can make use of environment variables to automatically +scale your pod replicas.
+It's important to note that when a project is deployed to a Kubernetes cluster,
+it relies on a Docker image that has been pushed to the
+GitLab Container Registry. Kubernetes
+fetches this image and uses it to run the application. If the project is public,
+the image can be accessed by Kubernetes without any authentication, allowing us
+to have deployments more usable. If the project is private/internal, the
+Registry requires credentials to pull the image. Currently, this is addressed
+by providing CI_JOB_TOKEN
as the password that can be used, but this token will
+no longer be valid as soon as the deployment job finishes. This means that
+Kubernetes can run the application, but in case it should be restarted or
+executed somewhere else, it cannot be accessed again.
++Introduced in GitLab 11.0.
+
For internal and private projects a GitLab Deploy Token +will be automatically created, when Auto DevOps is enabled and the Auto DevOps settings are saved. This Deploy Token +can be used for permanent access to the registry.
+Note: Note +When the GitLab Deploy Token has been manually revoked, it won't be automatically created.
+NOTE: Note: +Check the requirements for Auto Monitoring to make this stage +work.
+Once your application is deployed, Auto Monitoring makes it possible to monitor +your application's server and response metrics right out of the box. Auto +Monitoring uses Prometheus to +get system metrics such as CPU and memory usage directly from +Kubernetes, +and response metrics such as HTTP error rates, latency, and throughput from the +NGINX server.
+The metrics include:
+If GitLab has been deployed using the GitLab Omnibus Helm Chart, no +configuration is required.
+If you have installed GitLab using a different method, you need to:
+prometheus.io/scrape: "true"
and prometheus.io/port: "10254"
.To view the metrics, open the +Monitoring dashboard for a deployed environment.
+ +While Auto DevOps provides great defaults to get you started, you can customize
+almost everything to fit your needs; from custom buildpacks,
+to Dockerfile
s, Helm charts, or
+even copying the complete CI/CD configuration
+into your project to enable staging and canary deployments, and more.
If the automatic buildpack detection fails for your project, or if you want to
+use a custom buildpack, you can override the buildpack(s) using a project variable
+or a .buildpacks
file in your project:
BUILDPACK_URL
with the URL
+of the buildpack to use..buildpacks
file - Add a file in your project's repo called .buildpacks
+and add the URL of the buildpack to use on a line in the file. If you want to
+use multiple buildpacks, you can enter them in, one on each line.CAUTION: Caution: +Using multiple buildpacks isn't yet supported by Auto DevOps.
+Dockerfile
+If your project has a Dockerfile
in the root of the project repo, Auto DevOps
+will build a Docker image based on the Dockerfile rather than using buildpacks.
+This can be much faster and result in smaller images, especially if your
+Dockerfile is based on Alpine.
Auto DevOps uses Helm to deploy your application to Kubernetes. +You can override the Helm chart used by bundling up a chart into your project +repo or by specifying a project variable:
+./chart
directory with a Chart.yaml
+file in it, Auto DevOps will detect the chart and use it instead of the default
+one.
+This can be a great way to control exactly how your application is deployed.AUTO_DEVOPS_CHART
with the URL of a custom chart to use..gitlab-ci.yml
+If you want to modify the CI/CD pipeline used by Auto DevOps, you can copy the +Auto DevOps template into your project's repo and edit as you see fit.
+Assuming that your project is new or it doesn't have a .gitlab-ci.yml
file
+present:
+
), then "New file".gitlab-ci.yml
as the template typeTIP: Tip: The Auto DevOps template includes useful comments to help you
+customize it. For example, if you want deployments to go to a staging environment
+instead of directly to a production one, you can enable the staging
job by
+renaming .staging
to staging
. Then make sure to uncomment the when
key of
+the production
job to turn it into a manual action instead of deploying
+automatically.
In order to support applications that require a database,
+PostgreSQL is provisioned by default. The credentials to access
+the database are preconfigured, but can be customized by setting the associated
+variables. These credentials can be used for defining a
+DATABASE_URL
of the format:
postgres://user:password@postgres-host:postgres-port/postgres-database
+The following variables can be used for setting up the Auto DevOps domain, +providing a custom Helm chart, or scaling your application. PostgreSQL can be +also be customized, and you can easily use a custom buildpack.
+Variable | +Description | +
---|---|
AUTO_DEVOPS_DOMAIN |
+The Auto DevOps domain; by default set automatically by the Auto DevOps setting. | +
AUTO_DEVOPS_CHART |
+The Helm Chart used to deploy your apps; defaults to the one provided by GitLab. | +
REPLICAS |
+The number of replicas to deploy; defaults to 1. | +
PRODUCTION_REPLICAS |
+The number of replicas to deploy in the production environment. This takes precedence over REPLICAS ; defaults to 1. |
+
CANARY_REPLICAS |
+The number of canary replicas to deploy for Canary Deployments; defaults to 1 | +
CANARY_PRODUCTION_REPLICAS |
+The number of canary replicas to deploy for Canary Deployments in the production environment. This takes precedence over CANARY_REPLICAS ; defaults to 1 |
+
POSTGRES_ENABLED |
+Whether PostgreSQL is enabled; defaults to "true" . Set to false to disable the automatic deployment of PostgreSQL. |
+
POSTGRES_USER |
+The PostgreSQL user; defaults to user . Set it to use a custom username. |
+
POSTGRES_PASSWORD |
+The PostgreSQL password; defaults to testing-password . Set it to use a custom password. |
+
POSTGRES_DB |
+The PostgreSQL database name; defaults to the value of $CI_ENVIRONMENT_SLUG . Set it to use a custom database name. |
+
BUILDPACK_URL |
+The buildpack's full URL. It can point to either Git repositories or a tarball URL. For Git repositories, it is possible to point to a specific ref , for example https://github.com/heroku/heroku-buildpack-ruby.git#v142
+ |
+
SAST_CONFIDENCE_LEVEL |
+The minimum confidence level of security issues you want to be reported; 1 for Low, 2 for Medium, 3 for High; defaults to 3 . |
+
DEP_SCAN_DISABLE_REMOTE_CHECKS |
+Whether remote Dependency Scanning checks are disabled; defaults to "false" . Set to "true" to disable checks that send data to GitLab central servers. Read more about remote checks. |
+
STAGING_ENABLED |
+From GitLab 10.8, this variable can be used to define a deploy policy for staging and production environments. | +
CANARY_ENABLED |
+From GitLab 11.0, this variable can be used to define a deploy policy for canary environments. | +
INCREMENTAL_ROLLOUT_ENABLED |
+From GitLab 10.8, this variable can be used to enable an incremental rollout of your application for the production environment. | +
TEST_DISABLED |
+From GitLab 11.0, this variable can be used to disable the test job. If the variable is present, the job will not be created. |
+
CODEQUALITY_DISABLED |
+From GitLab 11.0, this variable can be used to disable the codequality job. If the variable is present, the job will not be created. |
+
SAST_DISABLED |
+From GitLab 11.0, this variable can be used to disable the sast job. If the variable is present, the job will not be created. |
+
DEPENDENCY_SCANNING_DISABLED |
+From GitLab 11.0, this variable can be used to disable the dependency_scanning job. If the variable is present, the job will not be created. |
+
CONTAINER_SCANNING_DISABLED |
+From GitLab 11.0, this variable can be used to disable the sast:container job. If the variable is present, the job will not be created. |
+
REVIEW_DISABLED |
+From GitLab 11.0, this variable can be used to disable the review and the manual review:stop job. If the variable is present, these jobs will not be created. |
+
DAST_DISABLED |
+From GitLab 11.0, this variable can be used to disable the dast job. If the variable is present, the job will not be created. |
+
PERFORMANCE_DISABLED |
+From GitLab 11.0, this variable can be used to disable the performance job. If the variable is present, the job will not be created. |
+
TIP: Tip: +Set up the replica variables using a +project variable +and scale your application by just redeploying it!
+CAUTION: Caution: +You should not scale your application using Kubernetes directly. This can +cause confusion with Helm not detecting the change, and subsequent deploys with +Auto DevOps can undo your changes.
+Apart from the two replica-related variables for production mentioned above, +you can also use others for different environments.
+There's a very specific mapping between Kubernetes' label named track
,
+GitLab CI/CD environment names, and the replicas environment variable.
+The general rule is: TRACK_ENV_REPLICAS
. Where:
TRACK
: The capitalized value of the track
+Kubernetes label
+in the Helm Chart app definition. If not set, it will not be taken into account
+to the variable name.ENV
: The capitalized environment name of the deploy job that is set in
+.gitlab-ci.yml
.That way, you can define your own TRACK_ENV_REPLICAS
variables with which
+you will be able to scale the pod's replicas easily.
In the example below, the environment's name is qa
and it deploys the track
+foo
which would result in looking for the FOO_QA_REPLICAS
environment
+variable:
QA testing:
+ stage: deploy
+ environment:
+ name: qa
+ script:
+ - deploy foo
+The track foo
being referenced would also need to be defined in the
+application's Helm chart, like:
replicaCount: 1
+image:
+ repository: gitlab.example.com/group/project
+ tag: stable
+ pullPolicy: Always
+ secrets:
+ - name: gitlab-registry
+application:
+ track: foo
+ tier: web
+service:
+ enabled: true
+ name: web
+ type: ClusterIP
+ url: http://my.host.com/
+ externalPort: 5000
+ internalPort: 5000
+++Introduced +in GitLab 10.8.
+
TIP: Tip: +You can also set this inside your project's settings.
+The normal behavior of Auto DevOps is to use Continuous Deployment, pushing
+automatically to the production
environment every time a new pipeline is run
+on the default branch. However, there are cases where you might want to use a
+staging environment and deploy to production manually. For this scenario, the
+STAGING_ENABLED
environment variable was introduced.
If STAGING_ENABLED
is defined in your project (e.g., set STAGING_ENABLED
to
+1
as a secret variable), then the application will be automatically deployed
+to a staging
environment, and a production_manual
job will be created for
+you when you're ready to manually deploy to production.
++Introduced +in GitLab 11.0.
+
A canary environment can be used +before any changes are deployed to production.
+If CANARY_ENABLED
is defined in your project (e.g., set CANARY_ENABLED
to
+1
as a secret variable) then two manual jobs will be created:
canary
which will deploy the application to the canary environmentproduction_manual
which is to be used by you when you're ready to manually
+deploy to production.++Introduced in GitLab 10.8.
+
TIP: Tip: +You can also set this inside your project's settings.
+When you have a new version of your app to deploy in production, you may want +to use an incremental rollout to replace just a few pods with the latest code. +This will allow you to first check how the app is behaving, and later manually +increasing the rollout up to 100%.
+If INCREMENTAL_ROLLOUT_ENABLED
is defined in your project (e.g., set
+INCREMENTAL_ROLLOUT_ENABLED
to 1
as a secret variable), then instead of the
+standard production
job, 4 different
+manual jobs
+will be created:
rollout 10%
rollout 25%
rollout 50%
rollout 100%
The percentage is based on the REPLICAS
variable and defines the number of
+pods you want to have for your deployment. If you say 10
, and then you run
+the 10%
rollout job, there will be 1
new pod + 9
old ones.
To start a job, click on the play icon next to the job's name. You are not
+required to go from 10%
to 100%
, you can jump to whatever job you want.
+You can also scale down by running a lower percentage job, just before hitting
+100%
. Once you get to 100%
, you cannot scale down, and you'd have to roll
+back by redeploying the old version using the
+rollback button in the
+environment page.
Below, you can see how the pipeline will look if the rollout or staging +variables are defined.
+Without INCREMENTAL_ROLLOUT_ENABLED
and without STAGING_ENABLED
Without INCREMENTAL_ROLLOUT_ENABLED
and with STAGING_ENABLED
With INCREMENTAL_ROLLOUT_ENABLED
and without STAGING_ENABLED
With INCREMENTAL_ROLLOUT_ENABLED
and with STAGING_ENABLED
NOTE: Note: +Not all buildpacks support Auto Test yet, as it's a relatively new +enhancement. All of Heroku's officially supported +languages +support it, and some third-party buildpacks as well e.g., Go, Node, Java, PHP, +Python, Ruby, Gradle, Scala, and Elixir all support Auto Test, but notably the +multi-buildpack does not.
+As of GitLab 10.0, the supported buildpacks are:
+- heroku-buildpack-multi v1.0.0
+- heroku-buildpack-ruby v168
+- heroku-buildpack-nodejs v99
+- heroku-buildpack-clojure v77
+- heroku-buildpack-python v99
+- heroku-buildpack-java v53
+- heroku-buildpack-gradle v23
+- heroku-buildpack-scala v78
+- heroku-buildpack-play v26
+- heroku-buildpack-php v122
+- heroku-buildpack-go v72
+- heroku-buildpack-erlang fa17af9
+- buildpack-nginx v8
+The following restrictions apply.
+CAUTION: Caution: Private project support in Auto DevOps is experimental.
+When a project has been marked as private, GitLab's Container +Registry requires authentication when downloading +containers. Auto DevOps will automatically provide the required authentication +information to Kubernetes, allowing temporary access to the registry. +Authentication credentials will be valid while the pipeline is running, allowing +for a successful initial deployment.
+After the pipeline completes, Kubernetes will no longer be able to access the +Container Registry. Restarting a pod, scaling a service, or other actions which +require on-going access to the registry may fail. On-going secure access is +planned for a subsequent release.
+Gemfile
to be properly detected, even though it is possible to write a
+Ruby app without a Gemfile
. Try specifying a custom
+buildpack..gitlab-ci.yml
with your test commands.If an administrator would like to disable the banners on an instance level, this +feature can be disabled either through the console:
+sudo gitlab-rails console
+Then run:
+Feature.get(:auto_devops_banner_disabled).enable
+Or through the HTTP API with an admin access token:
+curl --data "value=true" --header "PRIVATE-TOKEN: personal_access_token" https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled
+To prevent merge requests from accidentally being accepted before they're +completely ready, GitLab blocks the "Accept" button for merge requests that +have been marked a Work In Progress.
+ +To mark a merge request a Work In Progress, simply start its title with [WIP]
+or WIP:
. As an alternative, you're also able to do it by sending a commit
+with its title starting with wip
or WIP
to the merge request's source branch.
To allow a Work In Progress merge request to be accepted again when it's ready,
+simply remove the WIP
prefix.
Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time.
+Milestones allow you to organize issues and merge requests into a cohesive group, with an optional start date and an optional due date.
+++Note: +A permission level of
+Developer
or higher is required to create milestones.
To create a project milestone, navigate to Issues > Milestones in the project.
+Click the New milestone button. Enter the title, an optional description, an optional start date, and an optional due date. Click Create milestone to create the milestone.
+ +To create a group milestone, follow similar steps from above to project milestones. Navigate to Issues > Milestones in the group and create it from there.
+ +++Note: +A permission level of
+Developer
or higher is required to edit milestones.
You can update a milestone by navigating to Issues > Milestones in the project or group and clicking the Edit button.
+You can delete a milestone by clicking the Delete button.
+If you are expanding from a few projects to a larger number of projects within the same group, you may want to share the same milestone among multiple projects in the same group. If you previously created a project milestone and now want to make it available for other milestones, you can promote it to a group milestone.
+From the project milestone list page, you can promote a project milestone to a group milestone. This will merge all project milestones across all projects in this group with the same name into a single group milestones. All issues and merge requests that previously were assigned one of these project milestones will now be assigned the new group milestones. This action cannot be reversed and the changes are permanent.
+++ +Note: +Not all features on the project milestone view are available on the group milestone view. If you promote a project milestone to a group milestone, you will lose these features. See Milestone view to see which features are missing from the group milestone view.
+
Every issue and merge request can be assigned a milestone. The milestones are visible on every issue and merge request page, in the sidebar. They are also visible in the issue board. From the sidebar, you can assign or unassign a milestones to the object. You can also perform this as a quick action in a comment. As mentioned, for a given issue or merge request, both project milestones and group milestones can be selected and assigned to the object.
+From the project issue/merge request list pages and the group issue/merge request list pages, you can filter by both group milestones and project milestones.
+From project issue boards, you can filter by both group milestones and project milestones in the search and filter bar.
+When filtering by milestone, in addition to choosing a specific project milestone or group milestone, you can choose a special milestone filter.
+Not all features in the project milestone view are available in the group milestone view. This table summarizes the differences:
+Feature | +Project milestone view | +Group milestone view | +
---|---|---|
Title an description | +✓ | +✓ | +
Issues assigned to milestone | +✓ | ++ |
Merge requests assigned to milestone | +✓ | ++ |
Participants and labels used | +✓ | ++ |
Percentage complete | +✓ | +✓ | +
Start date and due date | +✓ | +✓ | +
Total issue time spent | +✓ | +✓ | +
Total issue weight | +✓ | ++ |
The milestone view shows the title and description.
+These features are only available for project milestones and not group milestones.
+The milestone sidebar on the milestone view shows the following:
+For project milestones only, the milestone sidebar shows the total issue weight of all issues that have the milestone assigned.
+ +++Notes:
+
Prometheus is a powerful time-series monitoring service, providing a flexible +platform for monitoring GitLab and other software products. +GitLab provides out of the box monitoring with Prometheus, providing easy +access to high quality time-series monitoring of GitLab services.
+Prometheus works by periodically connecting to data sources and collecting their +performance metrics via the various exporters. To view +and work with the monitoring data, you can either +connect directly to Prometheus or utilize a +dashboard tool like Grafana.
+++Note: +For installations from source you'll have to install and configure it yourself.
+
Prometheus and it's exporters are on by default, starting with GitLab 9.0.
+Prometheus will run as the gitlab-prometheus
user and listen on
+http://localhost:9090
. By default Prometheus is only accessible from the GitLab server itself.
+Each exporter will be automatically set up as a
+monitoring target for Prometheus, unless individually disabled.
To disable Prometheus and all of its exporters, as well as any added in the future:
+Edit /etc/gitlab/gitlab.rb
Add or find and uncomment the following line, making sure it's set to false
:
prometheus_monitoring['enable'] = false
+Save the file and reconfigure GitLab for the changes to +take effect
+++Note: +The following change was added in GitLab Omnibus 8.17. Although possible, +it's not recommended to change the port Prometheus listens +on as this might affect or conflict with other services running on the GitLab +server. Proceed at your own risk.
+
In order to access Prometheus from outside the GitLab server you will need to
+set a FQDN or IP in prometheus['listen_address']
.
+To change the address/port that Prometheus listens on:
Edit /etc/gitlab/gitlab.rb
Add or find and uncomment the following line:
+prometheus['listen_address'] = 'localhost:9090'
+Replace localhost:9090
with the address/port you want Prometheus to
+listen on. If you would like to allow access to Prometheus to hosts other
+than localhost
, leave out the host, or use 0.0.0.0
to allow public access:
prometheus['listen_address'] = ':9090'
+# or
+prometheus['listen_address'] = '0.0.0.0:9090'
+Save the file and reconfigure GitLab for the changes to +take effect
+You can visit http://localhost:9090
for the dashboard that Prometheus offers by default.
++Note: +If SSL has been enabled on your GitLab instance, you may not be able to access +Prometheus on the same browser as GitLab if using the same FQDN due to HSTS. We plan to +provide access via GitLab, but in the interim there are +some workarounds: using a separate FQDN, using server IP, using a separate browser for Prometheus, resetting HSTS, or +having Nginx proxy it.
+
The performance data collected by Prometheus can be viewed directly in the +Prometheus console or through a compatible dashboard tool. +The Prometheus interface provides a flexible query language to work +with the collected data where you can visualize their output. +For a more fully featured dashboard, Grafana can be used and has +official support for Prometheus.
+Sample Prometheus queries:
+(1 - ((node_memory_MemFree + node_memory_Cached) / node_memory_MemTotal)) * 100
+1 - rate(node_cpu{mode="idle"}[5m])
+irate(node_network_transmit_bytes[5m])
+irate(node_network_receive_bytes[5m])
+++Introduced in GitLab 9.0. +Pod monitoring introduced in GitLab 9.4.
+
If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and annotated Pods in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration][] to monitor them.
+To disable the monitoring of Kubernetes:
+Edit /etc/gitlab/gitlab.rb
Add or find and uncomment the following line and set it to false
:
prometheus['monitor_kubernetes'] = false
+Save the file and reconfigure GitLab for the changes to +take effect
+++Introduced in GitLab 9.3.
+
GitLab monitors its own internal service metrics, and makes them available at the /-/metrics
endpoint. Unlike other exporters, this endpoint requires authentication as it is available on the same URL and port as user traffic.
➔ Read more about the GitLab Metrics.
+There are a number of libraries and servers which help in exporting existing +metrics from third-party systems as Prometheus metrics. This is useful for cases +where it is not feasible to instrument a given system with Prometheus metrics +directly (for example, HAProxy or Linux system stats). You can read more in the +Prometheus exporters and integrations upstream documentation.
+While you can use any exporter you like with your GitLab installation, the +following ones documented here are bundled in the Omnibus GitLab packages +making it easy to configure and use.
+The node exporter allows you to measure various machine resources such as +memory, disk and CPU utilization.
+➔ Read more about the node exporter.
+The Redis exporter allows you to measure various Redis metrics.
+➔ Read more about the Redis exporter.
+The Postgres exporter allows you to measure various PostgreSQL metrics.
+➔ Read more about the Postgres exporter.
+The GitLab monitor exporter allows you to measure various GitLab metrics, pulled from Redis and the database.
+ ++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
++Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+GitLab CI in conjunction with GitLab Runner can use +Docker Engine to test and build any application.
+Docker is an open-source project that allows you to use predefined images to +run applications in independent "containers" that are run within a single Linux +instance. Docker Hub has a rich database of pre-built images that can be +used to test and build your applications.
+Docker, when used with GitLab CI, runs each job in a separate and isolated
+container using the predefined image that is set up in
+.gitlab-ci.yml
.
This makes it easier to have a simple and reproducible build environment that +can also run on your workstation. The added benefit is that you can test all +the commands that we will explore later from your shell, rather than having to +test them on a dedicated CI server.
+To use GitLab Runner with Docker you need to register a new Runner
+to use the docker
executor.
A one-line example can be seen below:
+sudo gitlab-runner register \
+ --url "https://gitlab.example.com/" \
+ --registration-token "PROJECT_REGISTRATION_TOKEN" \
+ --description "docker-ruby-2.1" \
+ --executor "docker" \
+ --docker-image ruby:2.1 \
+ --docker-postgres latest \
+ --docker-mysql latest
+The registered runner will use the ruby:2.1
Docker image and will run two
+services, postgres:latest
and mysql:latest
, both of which will be
+accessible during the build process.
The image
keyword is the name of the Docker image the Docker executor
+will run to perform the CI tasks.
By default, the executor will only pull images from Docker Hub,
+but this can be configured in the gitlab-runner/config.toml
by setting
+the Docker pull policy to allow using local images.
For more information about images and Docker Hub please read +the Docker Fundamentals documentation.
+The services
keyword defines just another Docker image that is run during
+your job and is linked to the Docker image that the image
keyword defines.
+This allows you to access the service image during build time.
The service image can run any application, but the most common use case is to
+run a database container, e.g., mysql
. It's easier and faster to use an
+existing image and run it as an additional container than install mysql
every
+time the project is built.
You are not limited to have only database services. You can add as many
+services you need to .gitlab-ci.yml
or manually modify config.toml
.
+Any image found at Docker Hub or your private Container Registry can be
+used as a service.
You can see some widely used services examples in the relevant documentation of +CI services examples.
+To better understand how the container linking works, read +Linking containers together.
+To summarize, if you add mysql
as service to your application, the image will
+then be used to create a container that is linked to the job container.
The service container for MySQL will be accessible under the hostname mysql
.
+So, in order to access your database service you have to connect to the host
+named mysql
instead of a socket or localhost
. Read more in accessing the
+services.
Services are designed to provide additional functionality which is network accessible.
+It may be a database like MySQL, or Redis, and even docker:stable-dind
which
+allows you to use Docker in Docker. It can be practically anything that is
+required for the CI/CD job to proceed and is accessed by network.
To make sure this works, the Runner:
+When the second stage of the check fails, either because there is no opened port in the
+service, or the service was not started properly before the timeout and the port is not
+responding, it prints the warning: *** WARNING: Service XYZ probably didn't start properly
.
In most cases it will affect the job, but there may be situations when the job +will still succeed even if that warning was printed. For example:
+/builds
). In that case, the service will do its job, and
+since the job is not trying to connect to it, it won't fail.As it was mentioned before, this feature is designed to provide network accessible +services. A database is the simplest example of such a service.
+NOTE: Note:
+The services feature is not designed to, and will not add any software from the
+defined services
image(s) to the job's container.
For example, if you have the following services
defined in your job, the php
,
+node
or go
commands will not be available for your script, and thus
+the job will fail:
job:
+ services:
+ - php:7
+ - node:latest
+ - golang:1.10
+ image: alpine:3.7
+ script:
+ - php -v
+ - node -v
+ - go version
+If you need to have php
, node
and go
available for your script, you should
+either:
Let's say that you need a Wordpress instance to test some API integration with +your application.
+You can then use for example the tutum/wordpress image in your
+.gitlab-ci.yml
:
services:
+- tutum/wordpress:latest
+If you don't specify a service alias,
+when the job is run, tutum/wordpress
will be started and you will have
+access to it from your build container under two hostnames to choose from:
tutum-wordpress
tutum__wordpress
++Note: +Hostnames with underscores are not RFC valid and may cause problems in 3rd party +applications.
+
The default aliases for the service's hostname are created from its image name +following these rules:
+:
) is stripped/
) is replaced with double underscores (__
) and the primary alias
+is created/
) is replaced with a single dash (-
) and the secondary alias is
+created (requires GitLab Runner v1.1.0 or higher)To override the default behavior, you can +specify a service alias.
+image
and services
from .gitlab-ci.yml
+You can simply define an image that will be used for all jobs and a list of +services that you want to use during build time:
+image: ruby:2.2
+
+services:
+ - postgres:9.3
+
+before_script:
+ - bundle install
+
+test:
+ script:
+ - bundle exec rake spec
+It is also possible to define different images and services per job:
+before_script:
+ - bundle install
+
+test:2.1:
+ image: ruby:2.1
+ services:
+ - postgres:9.3
+ script:
+ - bundle exec rake spec
+
+test:2.2:
+ image: ruby:2.2
+ services:
+ - postgres:9.4
+ script:
+ - bundle exec rake spec
+Or you can pass some extended configuration options
+for image
and services
:
image:
+ name: ruby:2.2
+ entrypoint: ["/bin/bash"]
+
+services:
+- name: my-postgres:9.4
+ alias: db-postgres
+ entrypoint: ["/usr/local/bin/db-postgres"]
+ command: ["start"]
+
+before_script:
+- bundle install
+
+test:
+ script:
+ - bundle exec rake spec
+++Introduced in GitLab and GitLab Runner 9.4.
+
When configuring the image
or services
entries, you can use a string or a map as
+options:
name
+option, which is the same name of the image as used for the string settingFor example, the following two definitions are equal:
+Using a string as an option to image
and services
:
image: "registry.example.com/my/image:latest"
+
+services:
+- postgresql:9.4
+- redis:latest
+Using a map as an option to image
and services
. The use of image:name
is
+required:
image:
+ name: "registry.example.com/my/image:latest"
+
+services:
+- name: postgresql:9.4
+- name: redis:latest
+image
+++Introduced in GitLab and GitLab Runner 9.4.
+
Setting | +Required | +GitLab version | +Description | +
---|---|---|---|
name |
+yes, when used with any other option | +9.4 | +Full name of the image that should be used. It should contain the Registry part if needed. | +
entrypoint |
+no | +9.4 | +Command or script that should be executed as the container's entrypoint. It will be translated to Docker's --entrypoint option while creating the container. The syntax is similar to Dockerfile 's ENTRYPOINT directive, where each shell token is a separate string in the array. |
+
services
+++Introduced in GitLab and GitLab Runner 9.4.
+
Setting | +Required | +GitLab version | +Description | +
---|---|---|---|
name |
+yes, when used with any other option | +9.4 | +Full name of the image that should be used. It should contain the Registry part if needed. | +
entrypoint |
+no | +9.4 | +Command or script that should be executed as the container's entrypoint. It will be translated to Docker's --entrypoint option while creating the container. The syntax is similar to Dockerfile 's ENTRYPOINT directive, where each shell token is a separate string in the array. |
+
command |
+no | +9.4 | +Command or script that should be used as the container's command. It will be translated to arguments passed to Docker after the image's name. The syntax is similar to Dockerfile 's CMD directive, where each shell token is a separate string in the array. |
+
alias |
+no | +9.4 | +Additional alias that can be used to access the service from the job's container. Read Accessing the services for more information. | +
++Introduced in GitLab and GitLab Runner 9.4. Read more about the extended +configuration options.
+
Before the new extended Docker configuration options, the following configuration +would not work properly:
+services:
+- mysql:latest
+- mysql:latest
+The Runner would start two containers using the mysql:latest
image, but both
+of them would be added to the job's container with the mysql
alias based on
+the default hostname naming. This would end with one
+of the services not being accessible.
After the new extended Docker configuration options, the above example would +look like:
+services:
+- name: mysql:latest
+ alias: mysql-1
+- name: mysql:latest
+ alias: mysql-2
+The Runner will still start two containers using the mysql:latest
image,
+but now each of them will also be accessible with the alias configured
+in .gitlab-ci.yml
file.
++Introduced in GitLab and GitLab Runner 9.4. Read more about the extended +configuration options.
+
Let's assume you have a super/sql:latest
image with some SQL database
+inside it and you would like to use it as a service for your job. Let's also
+assume that this image doesn't start the database process while starting
+the container and the user needs to manually use /usr/bin/super-sql run
as
+a command to start the database.
Before the new extended Docker configuration options, you would need to create
+your own image based on the super/sql:latest
image, add the default command,
+and then use it in job's configuration, like:
# my-super-sql:latest image's Dockerfile
+
+FROM super/sql:latest
+CMD ["/usr/bin/super-sql", "run"]
+# .gitlab-ci.yml
+
+services:
+- my-super-sql:latest
+After the new extended Docker configuration options, you can now simply
+set a command
in .gitlab-ci.yml
, like:
# .gitlab-ci.yml
+
+services:
+- name: super/sql:latest
+ command: ["/usr/bin/super-sql", "run"]
+As you can see, the syntax of command
is similar to Dockerfile's CMD
.
++Introduced in GitLab and GitLab Runner 9.4. Read more about the extended +configuration options.
+
Before showing the available entrypoint override methods, let's describe shortly +how the Runner starts and uses a Docker image for the containers used in the +CI jobs:
+Dockerfile
that may be overridden in .gitlab-ci.yml
)before_script
,
+script
,
+and after_script
).To override the entrypoint of a Docker image, the recommended solution is to
+define an empty entrypoint
in .gitlab-ci.yml
, so the Runner doesn't start
+a useless shell layer. However, that will not work for all Docker versions, and
+you should check which one your Runner is using. Specifically:
entrypoint
can be set to an empty value.entrypoint
can be set to
+/bin/sh -c
, /bin/bash -c
or an equivalent shell available in the image.The syntax of image:entrypoint
is similar to Dockerfile's ENTRYPOINT
.
Let's assume you have a super/sql:experimental
image with some SQL database
+inside it and you would like to use it as a base image for your job because you
+want to execute some tests with this database binary. Let's also assume that
+this image is configured with /usr/bin/super-sql run
as an entrypoint. That
+means that when starting the container without additional options, it will run
+the database's process, while Runner expects that the image will have no
+entrypoint or that the entrypoint is prepared to start a shell command.
With the extended Docker configuration options, instead of creating your
+own image based on super/sql:experimental
, setting the ENTRYPOINT
+to a shell, and then using the new image in your CI job, you can now simply
+define an entrypoint
in .gitlab-ci.yml
.
For Docker 17.06+:
+image:
+ name: super/sql:experimental
+ entrypoint: [""]
+For Docker =< 17.03:
+image:
+ name: super/sql:experimental
+ entrypoint: ["/bin/sh", "-c"]
+config.toml
+Look for the [runners.docker]
section:
[runners.docker]
+ image = "ruby:2.1"
+ services = ["mysql:latest", "postgres:latest"]
+The image and services defined this way will be added to all job run by +that runner.
+++Notes:
+
As an example, let's assume that you want to use the registry.example.com/private/image:latest
+image which is private and requires you to login into a private container registry.
Let's also assume that these are the login credentials:
+Key | +Value | +
---|---|
registry | +registry.example.com | +
username | +my_username | +
password | +my_password | +
To configure access for registry.example.com
, follow these steps:
Find what the value of DOCKER_AUTH_CONFIG
should be. There are two ways to
+accomplish this:
First way - Do a docker login
on your local machine:
docker login registry.example.com --username my_username --password my_password
+Then copy the content of ~/.docker/config.json
.
Second way - In some setups, it's possible that Docker client will use
+the available system keystore to store the result of docker login
. In
+that case, it's impossible to read ~/.docker/config.json
, so you will
+need to prepare the required base64-encoded version of
+${username}:${password}
manually. Open a terminal and execute the
+following command:
```bash
+echo -n "my_username:my_password" | base64
+
+# Example output to copy
+bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
+```
+Create a variable DOCKER_AUTH_CONFIG
with the content of the
+Docker configuration file as the value:
{
+ "auths": {
+ "registry.example.com": {
+ "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
+ }
+ }
+}
+Optionally,if you followed the first way of finding the DOCKER_AUTH_CONFIG
+value, do a docker logout
on your computer if you don't need access to the
+registry from it:
docker logout registry.example.com
+You can now use any private image from registry.example.com
defined in
+image
and/or services
in your .gitlab-ci.yml
file:
image: my.registry.tld:5000/namespace/image:tag
+In the example above, GitLab Runner will look at my.registry.tld:5000
for the
+image namespace/image:tag
.
You can add configuration for as many registries as you want, adding more
+registries to the "auths"
hash as described above.
Many services accept environment variables which allow you to easily change +database names or set account names depending on the environment.
+GitLab Runner 0.5.0 and up passes all YAML-defined variables to the created +service containers.
+For all possible configuration variables check the documentation of each image +provided in their corresponding Docker hub page.
+Note: All variables will be passed to all services containers. It's not +designed to distinguish which variable should go where.
+See the specific documentation for +using PostgreSQL as a service.
+See the specific documentation for +using MySQL as a service.
+Below is a high level overview of the steps performed by Docker during job +time.
+mysql
, postgresql
, mongodb
, redis
.config.toml
and
+Dockerfile
of build image (ruby:2.1
as in above example)./builds/group-name/project-name/
..gitlab-ci.yml
.Note: The following commands are run without root privileges. You should be +able to run Docker with your regular user account.
+First start with creating a file named build_script
:
cat <<EOF > build_script
+git clone https://gitlab.com/gitlab-org/gitlab-runner.git /builds/gitlab-org/gitlab-runner
+cd /builds/gitlab-org/gitlab-runner
+make
+EOF
+Here we use as an example the GitLab Runner repository which contains a
+Makefile, so running make
will execute the commands defined in the Makefile.
+Your mileage may vary, so instead of make
you could run the command which
+is specific to your project.
Then create some service containers:
+docker run -d --name service-mysql mysql:latest
+docker run -d --name service-postgres postgres:latest
+This will create two service containers, named service-mysql
and
+service-postgres
which use the latest MySQL and PostgreSQL images
+respectively. They will both run in the background (-d
).
Finally, create a build container by executing the build_script
file we
+created earlier:
docker run --name build -i --link=service-mysql:mysql --link=service-postgres:postgres ruby:2.1 /bin/bash < build_script
+The above command will create a container named build
that is spawned from
+the ruby:2.1
image and has two services linked to it. The build_script
is
+piped using STDIN to the bash interpreter which in turn executes the
+build_script
in the build
container.
When you finish testing and no longer need the containers, you can remove them +with:
+docker rm -f -v build service-mysql service-postgres
+This will forcefully (-f
) remove the build
container, the two service
+containers as well as all volumes (-v
) that were created with the container
+creation.
+Discover projects, groups and snippets. Share your projects with others +
++Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
++ +Already have login and password? +Sign in + +
++Discover projects, groups and snippets. Share your projects with others +
+Git is a free and open source +distributed version control system designed to handle everything from small to +very large projects with speed and efficiency.
+GitLab is a Git-based fully integrated platform for +software development. Besides Git's functionalities, GitLab has a lot of +powerful features to enhance your +workflow.
+We've gathered some resources to help you to get the best from Git with GitLab.
+Third-party references:
+Third-party references:
+ +GitLab comes with its own application performance measuring system as of GitLab +8.4, simply called "GitLab Performance Monitoring". GitLab Performance Monitoring is available in both the +Community and Enterprise editions.
+Apart from this introduction, you are advised to read through the following +documents in order to understand and properly configure GitLab Performance Monitoring:
+++Note: +Omnibus GitLab 8.16 includes Prometheus as an additional tool to collect +metrics. It will eventually replace InfluxDB when their metrics collection is +on par. Read more in the Prometheus documentation.
+
GitLab Performance Monitoring makes it possible to measure a wide variety of statistics +including (but not limited to):
+Metrics data is written to InfluxDB over UDP. Stored +data can be visualized using Grafana or any other application that +supports reading data from InfluxDB. Alternatively data can be queried using the +InfluxDB CLI.
+Two types of metrics are collected:
+Transaction metrics are metrics that can be associated with a single +transaction. This includes statistics such as the transaction duration, timings +of any executed SQL queries, time spent rendering HAML views, etc. These metrics +are collected for every Rack request and Sidekiq job processed.
+Sampled metrics are metrics that can't be associated with a single transaction. +Examples include garbage collection statistics and retained Ruby objects. These +metrics are collected at a regular interval. This interval is made up out of two +parts:
+The actual interval can be anywhere between a half of the defined interval and a +half above the interval. For example, for a user defined interval of 15 seconds +the actual interval can be anywhere between 7.5 and 22.5. The interval is +re-generated for every sampling run instead of being generated once and re-used +for the duration of the process' lifetime.
+NOTE: Note: +Only project Maintainers and Admin users have the permissions to access a project +settings.
+You can adjust your project settings by navigating +to your project's homepage and clicking Settings.
+Under a project's general settings you can find everything concerning the +functionality of a project.
+Adjust your project's name, description, avatar, default branch, and tags:
+ +Set up your project's access, visibility, and enable Container Registry for your projects:
+ +Add an issue description template to your project, so that every new issue will start with a custom template.
+Set up your project's merge request settings:
+Enable Service Desk for your project to offer customer support. Service Desk is available in GitLab Premium.
+Learn how to export a project in GitLab.
+Here you can run housekeeping, archive, rename, transfer, or remove a project.
+NOTE: Note: +Only project Owners and Admin users have the permissions to archive a project.
+Archiving a project makes it read-only for all users and indicates that it is +no longer actively maintained. Projects that have been archived can also be +unarchived.
+When a project is archived, the repository, issues, merge requests and all +other features are read-only. Archived projects are also hidden +in project listings.
+To archive a project:
+NOTE: Note: +Only project Maintainers and Admin users have the permissions to rename a +repository. Not to be confused with a project's name where it can also be +changed from the general project settings.
+A project's repository name defines its URL (the one you use to access the +project via a browser) and its place on the file disk where GitLab is installed.
+To rename a repository:
+Remember that this can have unintended side effects since everyone with the +old URL will not be able to push or pull. Read more about what happens with the +redirects when renaming repositories.
+NOTE: Note: +Only project Owners and Admin users have the permissions to transfer a project.
+You can transfer an existing project into a group if:
+Similarly, if you are an owner of a group, you can transfer any of its projects +under your own user.
+To transfer a project:
+Once done, you will be taken to the new project's namespace. At this point, +read what happens with the +redirects from the old project to the new one.
+NOTE: Note: +GitLab administrators can use the admin interface to move any project to any +namespace if needed.
+To search through issues and merge requests in multiple projects, you can use the left-sidebar.
+Click the menu bar, then Issues or Merge Requests, which work in the same way, +therefore, the following notes are valid for both.
+The number displayed on their right represents the number of issues and merge requests assigned to you.
+ +When you click Issues, you'll see the opened issues assigned to you straight away:
+ +You can filter them by Author, Assignee, Milestone, and Labels, +searching through Open, Closed, and All issues.
+Of course, you can combine all filters together.
+You'll find a shortcut to issues and merge requests create by you or assigned to you +on the search field on the top-right of your screen:
+ +If you want to search for issues present in a specific project, navigate to +a project's Issues tab, and click on the field Search or filter results.... It will +display a dropdown menu, from which you can add filters per author, assignee, milestone, +label, weight, and 'my-reaction' (based on your emoji votes). When done, press Enter on your keyboard to filter the issues.
+ +The same process is valid for merge requests. Navigate to your project's Merge Requests tab, +and click Search or filter results.... Merge requests can be filtered by author, assignee, +milestone, and label.
+You can filter issues and merge requests by specific terms included in titles or descriptions.
+display bug
will return all issues matching both those words, in any order."display bug"
+included in titles
is same as included titles
+Similar to Issues and merge requests per project, you can also search for issues +within a group. Navigate to a group's Issues tab and query search results in +the same way as you do for projects.
+ +The same process is valid for merge requests. Navigate to your project's Merge Requests tab.
+You can view recent searches by clicking on the little arrow-clock icon, which is to the left of the search input. Click the search entry to run that search again. This feature is available for issues and merge requests. Searches are stored locally in your browser.
+ +Individual filters can be removed by clicking on the filter's (x) button or backspacing. The entire search filter can be cleared by clicking on the search box's (x) button.
+You'll also find a shortcut on the search field on the top-right of the project's dashboard to +quickly access issues and merge requests created or assigned to you within that project:
+ +Your todos can be searched by "to do" and "done". +You can filter them per project, +author, type, and action. Also, you can sort them by +Label priority, +Last created and Oldest created.
+You can search through your projects from the left menu, by clicking the menu bar, then Projects. +On the field Filter by name, type the project or group name you want to find, and GitLab +will filter them for you as you type.
+You can also look for the projects you starred (Starred projects), and Explore all +public and internal projects available in GitLab.com, from which you can filter by visibility, +through Trending, best rated with Most starts, or All of them.
+You can also sort them by Name, Last created, Oldest created, Last updated, +Oldest updated, Owner, and choose to hide or show archived projects:
+ +Similarly to projects search, you can search through your groups from +the left menu, by clicking the menu bar, then Groups.
+On the field Filter by name, type the group name you want to find, and GitLab +will filter them for you as you type.
+You can also Explore all public and internal groups available in GitLab.com, +and sort them by Last created, Oldest created, Last updated, or Oldest updated.
+From an Issue Board, you can filter issues by Author, Assignee, Milestone, and Labels. +You can also filter them by name (issue title), from the field Filter by name, which is loaded as you type.
+When you want to search for issues to add to lists present in your Issue Board, click +the button Add issues on the top-right of your screen, opening a modal window from which +you'll be able to, besides filtering them by Name, Author, Assignee, Milestone, +and Labels, select multiple issues to add to a list of your choice:
+ ++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+This page gathers all the resources for the topic Authentication within GitLab.
++Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+Quick actions are textual shortcuts for common actions on issues or merge +requests that are usually done by clicking buttons or dropdowns in GitLab's UI. +You can enter these commands while creating a new issue or merge request, and +in comments. Each command should be on a separate line in order to be properly +detected and executed. The commands are removed from the issue, merge request or +comment body before it is saved and will not be visible to anyone else.
+Below is a list of all of the available commands and descriptions about what they +do.
+Command | +Action | +
---|---|
/close |
+Close the issue or merge request | +
/reopen |
+Reopen the issue or merge request | +
/merge |
+Merge (when pipeline succeeds) | +
/title <New title> |
+Change title | +
/assign @username |
+Assign | +
/unassign |
+Remove assignee | +
/milestone %milestone |
+Set milestone | +
/remove_milestone |
+Remove milestone | +
/label ~foo ~"bar baz" |
+Add label(s) | +
/unlabel ~foo ~"bar baz" |
+Remove all or specific label(s) | +
/relabel ~foo ~"bar baz" |
+Replace all label(s) | +
/todo |
+Add a todo | +
/done |
+Mark todo as done | +
/subscribe |
+Subscribe | +
/unsubscribe |
+Unsubscribe | +
/due <in 2 days | this Friday | December 31st> |
+Set due date | +
/remove_due_date |
+Remove due date | +
/wip |
+Toggle the Work In Progress status | +
/estimate <1w 3d 2h 14m> |
+Set time estimate | +
/remove_estimate |
+Remove estimated time | +
/spend <time(1h 30m | -1h 5m)> <date(YYYY-MM-DD)> |
+Add or subtract spent time; optionally, specify the date that time was spent on | +
/remove_time_spent |
+Remove time spent | +
/target_branch <Branch Name> |
+Set target branch for current merge request | +
/award :emoji: |
+Toggle award for :emoji: | +
/board_move ~column |
+Move issue to column on the board | +
/duplicate #issue |
+Closes this issue and marks it as a duplicate of another issue | +
/move path/to/project |
+Moves issue to another project | +
/tableflip |
+Append the comment with (╯°□°)╯︵ ┻━┻
+ |
+
/shrug |
+Append the comment with ¯\_(ツ)_/¯
+ |
+
/copy_metadata #issue | !merge_request |
+Copy labels and milestone from other issue or merge request | +
/confidential |
+Makes the issue confidential | +
+Discover projects, groups and snippets. Share your projects with others +
+++Introduced in GitLab 8.14
+
Mattermost commands give users an extra interface to perform common operations +from the chat environment. This allows one to, for example, create an issue as +soon as the idea was discussed in Mattermost.
+Mattermost 3.4 and up is required.
+If you have the Omnibus GitLab package installed, Mattermost is already bundled +in it. All you have to do is configure it. Read more in the +Omnibus GitLab Mattermost documentation.
+If Mattermost is installed on the same server as GitLab, the configuration process can be +done for you by GitLab.
+Go to the Mattermost Slash Command service on your project and click the 'Add to Mattermost' button.
+The configuration consists of two parts. First you need to enable the slash +commands in Mattermost and then enable the service in GitLab.
+This step is only required when using a source install, omnibus installs will be +preconfigured with the right settings.
+The first thing to do in Mattermost is to enable custom slash commands from +the administrator console.
+Log in with an account that has admin privileges and navigate to the system +console.
+ +Click Custom integrations and set Enable Custom Slash Commands, +Enable custom integrations to override usernames, and Override +custom integrations to override profile picture icons to true
+ +Click Save at the bottom to save the changes.
+Open a new tab for GitLab, go to your project's +Integrations page +and select the Mattermost command service to configure it. +A screen will appear with all the values you need to copy in Mattermost as +described in the next step. Leave the window open.
+++ +Note: +GitLab will propose some values for the Mattermost settings. The only one +required to copy-paste as-is is the Request URL, all the others are just +suggestions.
+
Proceed to the next step and create a slash command in Mattermost with the +above values.
+Now that you have enabled custom slash commands in Mattermost and opened +the Mattermost slash commands service in GitLab, it's time to copy these values +in a new slash command.
+Back to Mattermost, under your team page settings, you should see the +Integrations option.
+ +Go to the Slash Commands integration and add a new one by clicking the +Add Slash Command button.
+ +Fill in the options for the custom command as described in +step 2.
+++ +Note: +If you plan on connecting multiple projects, pick a slash command trigger +word that relates to your projects such as
+/gitlab-project-name
or even +just/project-name
. Only use/gitlab
if you will only connect a single +project to your Mattermost team.
After you setup all the values, copy the token (we will use it below) and +click Done.
+ +In GitLab, paste the Mattermost token you copied in the previous step and +check the Active checkbox.
+ +Click Save changes for the changes to take effect.
+You are now set to start using slash commands in Mattermost that talk to the +GitLab project you configured.
+The first time a user will interact with the newly created slash commands, +Mattermost will trigger an authorization process.
+ +This will connect your Mattermost user with your GitLab user. You can +see all authorized chat accounts in your profile's page under Chat.
+When the authorization process is complete, you can start interacting with +GitLab using the Mattermost commands.
+The available slash commands are:
+Command | +Description | +Example | +
---|---|---|
/<trigger> issue new <title> ⇧ Shift+↵ Enter <description> | +Create a new issue in the project that <trigger> is tied to. <description> is optional. |
+/gitlab issue new We need to change the homepage | +
/<trigger> issue show <issue-number> | +Show the issue with ID <issue-number> from the project that <trigger> is tied to. |
+/gitlab issue show 42 | +
/<trigger> deploy <environment> to <environment> | +Start the CI job that deploys from one environment to another, for example staging to production . CI/CD must be properly configured. |
+/gitlab deploy staging to production | +
To see a list of available commands to interact with GitLab, type the +trigger word followed by help. Example: /gitlab help
+ +The permissions to run the available commands derive from +the permissions you have on the project.
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+++Introduced in GitLab 9.0.
+
GitLab offers powerful integration with Prometheus for monitoring key metrics of your apps, directly within GitLab. +Metrics for each environment are retrieved from Prometheus, and then displayed +within the GitLab interface.
+ +There are two ways to setup Prometheus integration, depending on where your apps are running:
+Once enabled, GitLab will automatically detect metrics from known services in the metric library.
+++Note: Introduced in GitLab 10.5
+
GitLab can seamlessly deploy and manage Prometheus on a connected Kubernetes cluster, making monitoring of your apps easy.
+Once you have a connected Kubernetes cluster with Helm installed, deploying a managed Prometheus is as easy as a single click.
+Operations > Kubernetes
page, to view your connected clustersPrometheus is deployed into the gitlab-managed-apps
namespace, using the official Helm chart. Prometheus is only accessible within the cluster, with GitLab communicating through the Kubernetes API.
The Prometheus server will automatically detect and monitor nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following Kubernetes annotations:
+prometheus.io/scrape
to true
to enable monitoring of the resource.prometheus.io/port
to define the port of the metrics endpoint.prometheus.io/path
to define the path of the metrics endpoint. Defaults to /metrics
.CPU and Memory consumption is monitored, but requires naming conventions in order to determine the environment. If you are using Auto DevOps, this is handled automatically.
+The NGINX Ingress that is deployed by GitLab to clusters, is automatically annotated for monitoring providing key response metrics: latency, throughput, and error rates.
+Integration with Prometheus requires the following:
+Installing and configuring Prometheus to monitor applications is fairly straight forward.
+The actual configuration of Prometheus integration within GitLab is very simple. +All you will need is the DNS or IP address of the Prometheus server you'd like +to integrate with.
+http://prometheus.example.com/
.
+The Test Settings button can be used to confirm connectivity from GitLab
+to the Prometheus server.Once configured, GitLab will attempt to retrieve performance metrics for any +environment which has had a successful deployment.
+GitLab will automatically scan the Prometheus server for metrics from known serves like Kubernetes and NGINX, and attempt to identify individual environment. The supported metrics and scan process is detailed in our Prometheus Metric Library documentation.
+You can view the performance dashboard for an environment by clicking on the monitoring button.
+++Introduced in GitLab 9.2. +GitLab 9.3 added the numeric comparison of the 30 minute averages. +Requires Kubernetes metrics
+
Developers can view the performance impact of their changes within the merge +request workflow. When a source branch has been deployed to an environment, a sparkline and numeric comparison of the average memory consumption will appear. On the sparkline, a dot +indicates when the current changes were deployed, with up to 30 minutes of +performance data displayed before and after. The comparison shows the difference between the 30 minute average before and after the deployment. This information is updated after +each commit has been deployed.
+Once merged and the target branch has been redeployed, the metrics will switch +to show the new environments this revision has been deployed to.
+Performance data will be available for the duration it is persisted on the +Prometheus server.
+ +If the "No data found" screen continues to appear, it could be due to:
+$CI_ENVIRONMENT_SLUG
+with the name of your environment.++Introduced in GitLab 8.11.
+
Description templates allow you to define context-specific templates for issue +and merge request description fields for your project.
+By using the description templates, users that create a new issue or merge +request can select a description template to help them communicate with other +contributors effectively.
+Every GitLab project can define its own set of description templates as they +are added to the root directory of a GitLab project's repository.
+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.
Create a new Markdown (.md
) file inside the .gitlab/issue_templates/
+directory in your repository. Commit and push to your default branch.
Similarly to issue templates, create a new Markdown (.md
) file inside the
+.gitlab/merge_request_templates/
directory in your repository. Commit and
+push to your default branch.
Let's take for example that you've created the file .gitlab/issue_templates/Bug.md
.
+This will enable the Bug
dropdown option when creating or editing issues. When
+Bug
is selected, the content from the Bug.md
template file will be copied
+to the issue description field. The 'Reset template' button will discard any
+changes you made after picking the template and return it to its initial status.
We make use of Description Templates for Issues and Merge Requests within the GitLab Community Edition project. Please refer to the .gitlab
folder for some examples.
++Tip: +It is possible to use quick actions within description templates to quickly add labels, assignees, and milestones. The quick actions will only be executed if the user submitting the Issue or Merge Request has the permissions perform the relevant actions.
+
Here is an example for a Bug report template:
+Summary
+
+(Summarize the bug encountered concisely)
+
+
+Steps to reproduce
+
+(How one can reproduce the issue - this is very important)
+
+
+Example Project
+
+(If possible, please create an example project here on GitLab.com that exhibits the problematic behaviour, and link to it here in the bug report)
+
+(If you are using an older version of GitLab, this will also determine whether the bug has been fixed in a more recent version)
+
+
+What is the current bug behavior?
+
+(What actually happens)
+
+
+What is the expected correct behavior?
+
+(What you should see instead)
+
+
+Relevant logs and/or screenshots
+
+(Paste any relevant logs - please use code blocks (```) to format console output,
+logs, and code as it's very hard to read otherwise.)
+
+
+Possible fixes
+
+(If you can, link to the line of code that might be responsible for the problem)
+
+/label ~bug ~reproduced ~needs-investigation
+/cc @project-manager
+/assign @qa-tester
++Discover projects, groups and snippets. Share your projects with others +
+++Notes: +Introduced in GitLab 8.8.
+
v1
support was added in GitLab 8.9 to support Docker
+versions earlier than 1.10.With the Docker Container Registry integrated into GitLab, every project can +have its own space to store its Docker images.
+You can read more about Docker Registry at https://docs.docker.com/registry/introduction/.
+NOTE: Note: +If you cannot find the Container Registry entry under your project's settings, +that means that it is not enabled in your GitLab instance. Ask your administrator +to enable it.
+++Notes:
+
If you visit the Registry link under your project's menu, you can see the +explicit instructions to login to the Container Registry using your GitLab +credentials.
+For example if the Registry's URL is registry.example.com
, the you should be
+able to login with:
docker login registry.example.com
+Building and publishing images should be a straightforward process. Just make +sure that you are using the Registry URL with the namespace and project name +that is hosted on GitLab:
+docker build -t registry.example.com/group/project/image .
+docker push registry.example.com/group/project/image
+Your image will be named after the following scheme:
+<registry URL>/<namespace>/<project>/<image>
+GitLab supports up to three levels of image repository names.
+Following examples of image tags are valid:
+registry.example.com/group/project:some-tag
+registry.example.com/group/project/image:latest
+registry.example.com/group/project/my/image:rc1
+To download and run a container from images hosted in GitLab Container Registry,
+use docker run
:
docker run [options] registry.example.com/group/project/image [arguments]
+For more information on running Docker containers, visit the +Docker documentation.
+GitLab offers a simple Container Registry management panel. Go to your project +and click Registry in the project menu.
+This view will show you all tags in your project and will easily allow you to +delete them.
+++Note: +This feature requires GitLab 8.8 and GitLab Runner 1.2.
+
Make sure that your GitLab Runner is configured to allow building Docker images by +following the Using Docker Build +and Using the GitLab Container Registry documentation.
+++Personal Access tokens were introduced in GitLab 9.3. +Project Deploy Tokens were introduced in GitLab 10.7
+
If a project is private, credentials will need to be provided for authorization.
+The preferred way to do this, is either by using a personal access tokens or a project deploy token.
+The minimal scope needed for both of them is read_registry
.
Example of using a personal access token:
+docker login registry.example.com -u <your_username> -p <your_access_token>
+Check to make sure that the system clock on your Docker client and GitLab server have +been synchronized (e.g. via NTP).
+If you are using an S3-backed Registry, double check that the IAM +permissions and the S3 credentials (including region) are correct. See the +sample IAM policy +for more details.
+Check the Registry logs (e.g. /var/log/gitlab/registry/current
) and the GitLab production logs
+for errors (e.g. /var/log/gitlab/gitlab-rails/production.log
). You may be able to find clues
+there.
The optional debug server can be enabled by setting the registry debug address
+in your gitlab.rb
configuration.
registry['debug_addr'] = "localhost:5001"
+After adding the setting, reconfigure GitLab to apply the change.
+Use curl to request debug output from the debug server:
+curl localhost:5001/debug/health
+curl localhost:5001/debug/vars
+++NOTE: The following section is only recommended for experts.
+
Sometimes it's not obvious what is wrong, and you may need to dive deeper into +the communication between the Docker client and the Registry to find out +what's wrong. We will use a concrete example in the past to illustrate how to +diagnose a problem with the S3 setup.
+A user attempted to enable an S3-backed Registry. The docker login
step went
+fine. However, when pushing an image, the output showed:
The push refers to a repository [s3-testing.myregistry.com:4567/root/docker-test/docker-image]
+dc5e59c14160: Pushing [==================================================>] 14.85 kB
+03c20c1a019a: Pushing [==================================================>] 2.048 kB
+a08f14ef632e: Pushing [==================================================>] 2.048 kB
+228950524c88: Pushing 2.048 kB
+6a8ecde4cc03: Pushing [==> ] 9.901 MB/205.7 MB
+5f70bf18a086: Pushing 1.024 kB
+737f40e80b7f: Waiting
+82b57dbc5385: Waiting
+19429b698a22: Waiting
+9436069b92a3: Waiting
+error parsing HTTP 403 response body: unexpected end of JSON input: ""
+This error is ambiguous, as it's not clear whether the 403 is coming from the +GitLab Rails application, the Docker Registry, or something else. In this +case, since we know that since the login succeeded, we probably need to look +at the communication between the client and the Registry.
+The REST API between the Docker client and Registry is described +here. Normally, one would just +use Wireshark or tcpdump to capture the traffic and see where things went +wrong. However, since all communication between Docker clients and servers +are done over HTTPS, it's a bit difficult to decrypt the traffic quickly even +if you know the private key. What can we do instead?
+One way would be to disable HTTPS by setting up an insecure +Registry. This could introduce a +security hole and is only recommended for local testing. If you have a +production system and can't or don't want to do this, there is another way: +use mitmproxy, which stands for Man-in-the-Middle Proxy.
+mitmproxy allows you to place a proxy between your +client and server to inspect all traffic. One wrinkle is that your system +needs to trust the mitmproxy SSL certificates for this to work.
+The following installation instructions assume you are running Ubuntu:
+Install mitmproxy (see http://docs.mitmproxy.org/en/stable/install.html)
+Run mitmproxy --port 9000
to generate its certificates.
+Enter CTRL-C to quit.
Install the certificate from ~/.mitmproxy
to your system:
sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt
+sudo update-ca-certificates
+If successful, the output should indicate that a certificate was added:
+Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done.
+Running hooks in /etc/ca-certificates/update.d....done.
+To verify that the certificates are properly installed, run:
+mitmproxy --port 9000
+This will run mitmproxy on port 9000
. In another window, run:
curl --proxy http://localhost:9000 https://httpbin.org/status/200
+If everything is setup correctly, you will see information on the mitmproxy window and +no errors from the curl commands.
+For Docker to connect through a proxy, you must start the Docker daemon with the
+proper environment variables. The easiest way is to shutdown Docker (e.g. sudo initctl stop docker
)
+and then run Docker by hand. As root, run:
export HTTP_PROXY="http://localhost:9000"
+export HTTPS_PROXY="https://localhost:9000"
+docker daemon --debug
+This will launch the Docker daemon and proxy all connections through mitmproxy.
+Now that we have mitmproxy and Docker running, we can attempt to login and push +a container image. You may need to run as root to do this. For example:
+docker login s3-testing.myregistry.com:4567
+docker push s3-testing.myregistry.com:4567/root/docker-test/docker-image
+In the example above, we see the following trace on the mitmproxy window:
+ +The above image shows:
+What does this mean? This strongly suggests that the S3 user does not have the right +permissions to perform a HEAD request. +The solution: check the IAM permissions again. +Once the right permissions were set, the error will go away.
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+Welcome to GitLab! We're glad to have you here!
+As a GitLab user you'll have access to all the features +your subscription +includes, except GitLab administrator +settings, unless you have admin privileges to install, configure, +and upgrade your GitLab instance.
+For GitLab.com, admin privileges are restricted to the GitLab team.
+If you run your own GitLab instance and are looking for the administration settings, +please refer to the administration +documentation.
+GitLab is a fully integrated software development platform that enables you +and your team to work cohesively, faster, transparently, and effectively, +since the discussion of a new idea until taking that idea to production all +the way through, from within the same platform.
+Please check this page for an overview on GitLab's features.
+For an overview on concepts involved when developing code on GitLab, +read the articles on:
+GitLab is a Git-based platform that integrates a great number of essential tools for software development and deployment, and project management:
+With GitLab Enterprise Edition, you can also:
+You can also integrate GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, HipChat, Trello, Slack, Bamboo CI, JIRA, and a lot more.
+In GitLab, you can create projects for numerous reasons, such as, host +your code, use it as an issue tracker, collaborate on code, and continuously +build, test, and deploy your app with built-in GitLab CI/CD. Or, you can do +it all at once, from one single project.
+Use built-in GitLab CI/CD to test, build, and deploy your applications +directly from GitLab. No third-party integrations needed.
+There is a lot you can customize and configure +to enjoy the best of GitLab.
+With GitLab Groups you can assemble related projects together +and grant members access to several projects at once.
+Groups can also be nested in subgroups.
+In GitLab, you can comment and mention collaborators in issues, +merge requests, code snippets, and commits.
+When performing inline reviews to implementations +to your codebase through merge requests you can +gather feedback through resolvable discussions.
+Read through the GFM documentation to learn how to apply +the best of GitLab Flavored Markdown in your discussions, comments, +issues and merge requests descriptions, and everywhere else GMF is +supported.
+Never forget to reply to your collaborators. GitLab Todos +are a tool for working faster and more effectively with your team, +by listing all user or group mentions, as well as issues and merge +requests you're assigned to.
+Search and filter through groups, projects, issues, merge requests, files, code, and more.
+Snippets are code blocks that you want to store in GitLab, from which +you have quick access to. You can also gather feedback on them through +discussions.
+Integrate GitLab with your preferred tool, +such as Trello, JIRA, etc.
+Configure webhooks to listen for +specific events like pushes, issues or merge requests. GitLab will send a +POST request with data to the webhook URL.
+Automate GitLab via API.
+Learn what is Git and its best practices.
+With GitLab Groups you can assemble related projects together +and grant members access to several projects at once.
+Groups can also be nested in subgroups.
+Find your groups by expanding the left menu and clicking Groups:
+ +The Groups page displays all groups you are a member of, how many projects it holds, +how many members it has, the group visibility, and, if you have enough permissions, +a link to the group settings. By clicking the last button you can leave that group.
+You can create groups for numerous reasons. To name a few:
+@mention
all the team at once in issues and merge requests
+company-team
, and among others,
+you created subgroups in this group for each individual team backend-team
,
+frontend-team
, and production-team
:
+1. When you start a new implementation from an issue, you add a comment:
+"@company-team
, let's do it! @company-team/backend-team
you're good to go!"
+1. When your backend team needs help from frontend, they add a comment:
+"@company-team/frontend-team
could you help us here please?"
+1. When the frontend team completes their implementation, they comment:
+"@company-team/backend-team
, it's done! Let's ship it @company-team/production-team
!"
+In GitLab, a namespace is a unique name to be used as a user name, a group name, or a subgroup name.
+http://gitlab.example.com/username
http://gitlab.example.com/groupname
http://gitlab.example.com/groupname/subgroup_name
For example, consider a user named Alex:
+alex
;
+their profile will be accessed under https://gitlab.example.com/alex
+alex-team
;
+the group and its projects will be accessed under https://gitlab.example.com/alex-team
+alex-team
with the subgroup name marketing
;
+this subgroup and its projects will be accessed under https://gitlab.example.com/alex-team/marketing
+By doing so:
+@alex
+@alex-team
+@alex-team/marketing
+Issues and merge requests are part of projects. For a given group, view all the +issues and merge requests across all the projects in that group, +together in a single list view.
+++Notes:
+
You can create a group in GitLab from:
+The Groups page: expand the left menu, click Groups, and click the green button New group:
+ +Elsewhere: expand the plus
sign button on the top navbar and choose New group:
Add the following information:
+ +Add members to a group by navigating to the group's dashboard, and clicking Members:
+ +Select the permission level and add the new member. You can also set the expiring +date for that user, from which they will no longer have access to your group.
+One of the benefits of putting multiple projects in one group is that you can +give a user to access to all projects in the group with one action.
+Consider we have a group with two projects:
+If necessary, you can increase the access level of an individual user for a specific project, +by adding them again as a new member to the project with the new permission levels.
+As a group owner you can enable or disable non members to request access to +your group. Go to the group settings and click on Allow users to request access.
+As a user, you can request to be a member of a group. Go to the group you'd +like to be a member of, and click the Request Access button on the right +side of your screen.
+ +Group owners and maintainers will be notified of your request and will be able to approve or +decline it on the members page.
+ +If you change your mind before your request is approved, just click the +Withdraw Access Request button.
+ +There are two different ways to add a new project to a group:
+Select a group and then click on the New project button.
+ +You can then continue on creating a project.
+While you are creating a project, select a group namespace +you've already created from the dropdown menu.
+ +Learn how to transfer a project into a group.
+You can share your projects with a group +and give your group members access to the project all at once.
+Alternatively, you can lock the sharing with group feature.
+In GitLab Enterprise Edition it is possible to manage GitLab group memberships using LDAP groups. +See the GitLab Enterprise Edition documentation for more information.
+From 10.5 there are two different ways to transfer a group:
+Please make sure to understand that:
+Once you have created a group, you can manage its settings by navigating to +the group's dashboard, and clicking Settings.
+ +Besides giving you the option to edit any settings you've previously +set when creating the group, you can also +access further configurations for your group.
+Changing a group's path can have unintended side effects. Read +how redirects will behave +before proceeding.
+If you are vacating the path so it can be claimed by another group or user, +you may need to rename the group name as well since both names and paths must +be unique.
+To change your group path:
+CAUTION: Caution: +It is currently not possible to rename a namespace if it contains a +project with Container Registry tags, +because the project cannot be moved.
+TIP: TIP: +If you want to retain ownership over the original namespace and +protect the URL redirects, then instead of changing a group's path or renaming a +username, you can create a new group and transfer projects to it.
+Add a security layer to your group by +enforcing two-factor authentication (2FA) +to all group members.
+Prevent projects in a group from sharing +a project with another group. +This allows for tighter control over project access.
+For example, consider you have two distinct teams (Group A and Group B) +working together in a project. +To inherit the group membership, you share the project between the +two groups A and B. Share with group lock prevents any project within +the group from being shared with another group. By doing so, you +guarantee only the right group members have access to that projects.
+To enable this feature, navigate to the group settings page. Select +Share with group lock and Save the group.
+ +With Member Lock it is possible to lock membership in project to the +level of members in group.
+Learn more about Member Lock.
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+With GitLab Pages it's easy to publish your project website. GitLab Pages is a hosting service for static websites, at no additional cost.
+Create a project from scratch +to get you started quickly, or, +alternatively, start from an existing project as follows:
+Further steps (optional):
+Watch a video with the steps above: https://www.youtube.com/watch?v=TWqh9MtT4Bg
+Advanced options:
+With GitLab Pages you can create static websites +for your GitLab projects, groups, or user accounts.
+It supports plain static content, such as HTML, and all static site generators (SSGs), such as Jekyll, Middleman, Hexo, Hugo, and Pelican.
+Connect as many custom domains as you like and bring your own TLS certificate +to secure them.
+Your files live in a project repository on GitLab.
+GitLab CI picks up those files and makes them available at, typically,
+https://<username>.gitlab.io/<projectname>
. Please read through the docs on
+GitLab Pages domains for more info.
Read the following tutorials to know more about:
+.gitlab-ci.yml
for your siteBlog posts series about Static Site Generators (SSGs):
+Blog posts for securing GitLab Pages custom domains with SSL/TLS certificates:
+Enable and configure GitLab Pages on your own instance (GitLab Community Edition and Enterprise Editions) with +the admin guide.
+Watch the video: https://www.youtube.com/watch?v=dD8c7WNcc6s
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+Learn how to administer your GitLab instance (Community Edition and +Enterprise Edition). +Regular users don't have access to GitLab administration tools and settings.
+GitLab has two product distributions: the open source +GitLab Community Edition (CE), +and the open core GitLab Enterprise Edition (EE), +available through different subscriptions.
+You can install GitLab CE or GitLab EE, +but the features you'll have access to depend on the subscription you choose +(Core, Starter, Premium, or Ultimate). GitLab Community Edition installations +only have access to Core features.
+GitLab.com is administered by GitLab, Inc., therefore, only GitLab team members have +access to its admin configurations. If you're a GitLab.com user, please check the +user documentation.
+Learn how to install, configure, update, and maintain your GitLab instance.
+++Note: Starting from version 8.0, GitLab Continuous Integration (CI) +is fully integrated into GitLab itself and is enabled by default on all +projects.
+
GitLab offers a continuous integration service. If you
+add a .gitlab-ci.yml
file to the root directory of your repository,
+and configure your GitLab project to use a Runner, then each commit or
+push, triggers your CI pipeline.
The .gitlab-ci.yml
file tells the GitLab runner what to do. By default it runs
+a pipeline with three stages: build
, test
, and deploy
. You don't need to
+use all three stages; stages with no jobs are simply ignored.
If everything runs OK (no non-zero return values), you'll get a nice green +checkmark 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 code.
+Most projects use GitLab's CI service to run the test suite so that +developers get immediate feedback if they broke something.
+There's a growing trend to use continuous delivery and continuous deployment to +automatically deploy tested code to staging and production environments.
+So in brief, the steps needed to have a working CI can be summed up to:
+.gitlab-ci.yml
to the root directory of your repositoryFrom there on, on every push to your Git repository, the Runner will +automagically start the pipeline and the pipeline will appear under the +project's Pipelines page.
+This guide assumes that you:
+Let's break it down to pieces and work on solving the GitLab CI puzzle.
+.gitlab-ci.yml
fileBefore you create .gitlab-ci.yml
let's first explain in brief what this is
+all about.
.gitlab-ci.yml
+The .gitlab-ci.yml
file is where you configure what CI does with your project.
+It lives in the root of your repository.
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.
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.
.gitlab-ci.yml
file++Note: +
+.gitlab-ci.yml
is a YAML file +so you have to pay extra attention to indentation. Always use spaces, not tabs.
You need to create a file named .gitlab-ci.yml
in the root directory of your
+repository. Below is an example for a Ruby on Rails project.
before_script:
+ - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
+ - ruby -v
+ - which ruby
+ - gem install bundler --no-ri --no-rdoc
+ - bundle install --jobs $(nproc) "${FLAGS[@]}"
+
+rspec:
+ script:
+ - bundle exec rspec
+
+rubocop:
+ script:
+ - bundle exec rubocop
+This is the simplest possible configuration that will work for most Ruby +applications:
+rspec
and rubocop
(the names are arbitrary) with
+different commands to be executed.before_script
are executed.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 and executed within the environment of the Runner.
What is important is that each job is run independently from each other.
+If you want to check whether the .gitlab-ci.yml
of your project is valid, there is a
+Lint tool under the page /ci/lint
of your project namespace. You can also find
+a "CI Lint" button to go to this page under CI/CD ➔ Pipelines and
+Pipelines ➔ Jobs in your project.
For more information and a complete .gitlab-ci.yml
syntax, please read
+the reference documentation on .gitlab-ci.yml.
.gitlab-ci.yml
to GitLabOnce you've created .gitlab-ci.yml
, you should add it to your Git repository
+and push it to GitLab.
git add .gitlab-ci.yml
+git commit -m "Add .gitlab-ci.yml"
+git push origin master
+Now if you go to the Pipelines page you will see that the pipeline is +pending.
+NOTE: Note: +If you have a mirrored repository where GitLab pulls from, +you may need to enable pipeline triggering in your project's +Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates.
+You can also go to the Commits page and notice the little pause icon next +to the commit SHA.
+ +Clicking on it you will be directed to the jobs page for that specific commit.
+ +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.
The next step is to configure a Runner so that it picks the pending jobs.
+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 Runners communicate through an API,
+so the only requirement is that the Runner's machine has network access to the
+GitLab server.
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.
+Find more information about different Runners in the +Runners documentation.
+You can find whether any Runners are assigned to your project by going to +Settings ➔ CI/CD. Setting up a Runner is easy and straightforward. The +official Runner supported by GitLab is written in Go and its documentation +can be found at https://docs.gitlab.com/runner/.
+In order to have a functional Runner you need to follow two steps:
+ +Follow the links above to set up your own Runner or use a Shared Runner as +described in the next section.
+Once the Runner has been set up, you should see it on the Runners page of your +project, following Settings ➔ CI/CD.
+ +If you use GitLab.com you can use the Shared Runners +provided by GitLab Inc.
+These are special virtual machines that run on GitLab's infrastructure and can +build any project.
+To enable the Shared Runners you have to go to your project's +Settings ➔ CI/CD and click Enable shared runners.
+ +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.
+ +Or you can view all jobs, by going to the Pipelines ➔ Jobs page.
+ +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.
+ +You are also able to view the status of any commit in the various pages in +GitLab, such as Commits and Merge requests.
+Visit the examples README to see a list of examples using GitLab +CI with various languages.
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++ ++
The GitLab Issue Board is a software project management tool used to plan, +organize, and visualize a workflow for a feature or product release. +It can be used as a Kanban or a Scrum board.
+ +The Issue Board builds on GitLab's existing +issue tracking functionality and +leverages the power of labels by utilizing them as lists of the scrum board.
+With the Issue Board you can have a different view of your issues while +maintaining the same filtering and sorting abilities you see across the +issue tracker. An Issue Board is based on its project's label structure, therefore, it +applies the same descriptive labels to indicate placement on the board, keeping +consistency throughout the entire development lifecycle.
+An Issue Board shows you what issues your team is working on, who is assigned to each, +and where in the workflow those issues are.
+You create issues, host code, perform reviews, build, test, +and deploy from one single platform. Issue Boards help you to visualize +and manage the entire process in GitLab.
+With Multiple Issue Boards, available +only in GitLab Enterprise Edition, +you go even further, as you can not only keep yourself and your project +organized from a broader perspective with one Issue Board per project, +but also allow your team members to organize their own workflow by creating +multiple Issue Boards within the same project.
+For a visual overview, see our Issue Board feature page +on about.gitlab.com or our video introduction to Issue Boards.
+There are many ways to use GitLab Issue Boards tailored to your own preferred workflow. +Here are some common use cases for Issue Boards.
+GitLab Workflow allows you to discuss proposals in issues, categorize them +with labels, and from there organize and prioritize them with Issue Boards.
+For example, let's consider this simplified development workflow:
+If we have the labels "backend", "frontend", "staging", and +"production", and an Issue Board with a list for each, we can:
+With Multiple Issue Boards, available only in +GitLab Enterprise Edition, +each team can have their own board to organize their workflow individually.
+With multiple Issue Boards, each team has one board. Now you can move issues through each +part of the process. For instance: To Do, Doing, and Done.
+Create lists to order things by topic and quickly change them between topics or groups, +such as between UX, Frontend, and Backend. The changes will be reflected across boards, +as changing lists will update the label accordingly.
+For example, suppose we have a UX team with an Issue Board that contains:
+When done with something, they move the card to Frontend. The Frontend team's board looks like:
+Cards finished by the UX team will automatically appear in the Frontend column when they're ready for them.
+NOTE: Note: +For a broader use case, please see the blog post +GitLab Workflow, an Overview. +For a real use case example, you can read why +Codepen decided to adopt Issue Boards +to improve their workflow with multiple boards.
+Create lists for each of your team members and quickly drag-and-drop issues onto each team member.
+Developers and up can use all the functionality of the +Issue Board, that is, create or delete lists and drag issues from one list to another.
+If you are not able to perform one or more of the things above, make sure you +have the right permissions.
+The first time you navigate to your Issue Board, you will be presented with +a default list (Done) and a welcoming message that gives +you two options. You can either create a predefined set of labels and create +their corresponding lists to the Issue Board or opt-out and use your own lists.
+ +If you choose to use and create the predefined lists, they will appear as empty +because the labels associated to them will not exist up until that moment, +which means the system has no way of populating them automatically. That's of +course if the predefined labels don't already exist. If any of them does exist, +the list will be created and filled with the issues that have that label.
+Create a new list by clicking on the Add list button at the upper +right corner of the Issue Board.
+ +Simply choose the label or user to create the list from. The new list will be inserted +at the end of the lists, before Done. Moving and reordering lists is as +easy as dragging them around.
+To create a list for a label that doesn't yet exist, simply create the label by +choosing Create new label. The label will be created on-the-fly and it will +be immediately added to the dropdown. You can now choose it to create a list.
+To delete a list from the Issue Board use the small trash icon that is present +in the list's heading. A confirmation dialog will appear for you to confirm.
+Deleting a list doesn't have any effect in issues and labels, it's just the +list view that is removed. You can always add it back later if you need.
+You can add issues to a list by clicking the Add issues button that is +present in the upper right corner of the Issue Board. This will open up a modal +window where you can see all the issues that do not belong to any list.
+Select one or more issues by clicking on the cards and then click Add issues +to add them to the selected list. You can limit the issues you want to add to +the list by filtering by author, assignee, milestone and label.
+ +Removing an issue from a list can be done by clicking on the issue card and then +clicking the Remove from board button in the sidebar. Under the hood, the +respective label is removed, and as such it's also removed from the list and the +board itself.
+ +When visiting a board, issues appear ordered in any list. You are able to change +that order simply by dragging and dropping the issues. The changed order will be saved +to the system so that anybody who visits the same board later will see the reordering, +with some exceptions.
+The first time a given issue appears in any board (i.e. the first time a user +loads a board containing that issue), it will be ordered with +respect to other issues in that list according to Priority order.
+At that point, that issue will be assigned a relative order value by the system +representing its relative order with respect to the other issues in the list. Any time +you drag-and-drop reorder that issue, its relative order value will change accordingly.
+Also, any time that issue appears in any board when it is loaded by a user,
+the updated relative order value will be used for the ordering. (It's only the first
+time an issue appears that it takes from the Priority order mentioned above.) This means that
+if issue A
is drag-and-drop reordered to be above issue B
by any user in
+a given board inside your GitLab instance, any time those two issues are subsequently
+loaded in any board in the same instance (could be a different project board or a different group board, for example),
+that ordering will be maintained.
You should be able to use the filters on top of your Issue Board to show only +the results you want. This is similar to the filtering used in the issue tracker +since the metadata from the issues and labels are re-used in the Issue Board.
+You can filter by author, assignee, milestone and label.
+By reordering your lists, you can create workflows. As lists in Issue Boards are +based on labels, it works out of the box with your existing issues. So if you've +already labeled things with 'Backend' and 'Frontend', the issue will appear in +the lists as you create them. In addition, this means you can easily move +something between lists by changing a label.
+A typical workflow of using the Issue Board would be:
+For instance you can create a list based on the label of 'Frontend' and one for +'Backend'. A designer can start working on an issue by adding it to the +'Frontend' list. That way, everyone knows that this issue is now being +worked on by the designers. Then, once they're done, all they have to do is +drag it over to the next list, 'Backend', where a backend developer can +eventually pick it up. Once they’re done, they move it to Done, to close the +issue.
+This process can be seen clearly when visiting an issue since with every move +to another list the label changes and a system not is recorded.
+ +++Introduced in GitLab Enterprise Edition 8.13.
+
Multiple Issue Boards, as the name suggests, allow for more than one Issue Board +for a given project or group. This is great for large projects with more than one team +or in situations where a repository is used to host the code of multiple +products.
+Clicking on the current board name in the upper left corner will reveal a +menu from where you can create another Issue Board and rename or delete the +existing one.
+NOTE: Note: +The Multiple Issue Boards feature is available for +projects in GitLab Starter Edition and for groups in GitLab Premium Edition.
+ +++Introduced in GitLab Starter Edition 10.2.
+
An Issue Board can be associated with GitLab Milestone, +Labels, Assignee and Weight +which will automatically filter the Board issues according to these fields. +This allows you to create unique boards according to your team's need.
+ +You can define the scope of your board when creating it or by clicking on the "Edit board" button. Once a milestone, assignee or weight is assigned to an Issue Board, you will no longer be able to filter +through these in the search bar. In order to do that, you need to remove the desired scope (e.g. milestone, assignee or weight) from the Issue Board.
+ +If you don't have editing permission in a board, you're still able to see the configuration by clicking on "View scope".
+ +++Introduced in GitLab Starter 9.1.
+
Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board.
+ +++Introduced in GitLab Premium 10.0.
+
Accessible at the group navigation level, a group issue board offers the same features as a project-level board, +but it can display issues from all projects in that +group and its descendant subgroups. Similarly, you can only filter by group labels for these +boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only +group-level objects are available.
+NOTE: Note: +Multiple group issue boards were originally introduced in GitLab 10.0 Premium and +one group issue board per group was made available in GitLab 10.6 Core.
+ +++Introduced in GitLab 11.0 Premium.
+
Like a regular list that shows all issues that have the list label, you can add +an assignee list that shows all issues assigned to the given user. +You can have a board with both label lists and assignee lists. To add an +assignee list:
+Now that the assignee list is added, you can assign or unassign issues to that user +by dragging issues to and/or from an assignee list. +To remove an assignee list, just as with a label list, click the trash icon.
+ +When dragging issues between lists, different behavior occurs depending on the source list and the target list.
++ | To Backlog | +To Closed | +To label B list |
+To assignee Bob list |
+
---|---|---|---|---|
From Backlog | +- | +Issue closed | +
+B added |
+
+Bob assigned |
+
From Closed | +Issue reopened | +- | +Issue reopenedB added |
+Issue reopenedBob assigned |
+
From label A list |
+
+A removed |
+Issue closed | +
+A removedB added |
+
+Bob assigned |
+
From assignee Alice list |
+
+Alice unassigned |
+Issue closed | +
+B added |
+
+Alice unassignedBob assigned |
+
Different issue board features are available in different GitLab tiers, as shown in the following table:
+Tier | +Number of Project Issue Boards | +Number of Group Issue Boards | +Configurable Project Issue Boards | +Configurable Group Issue Boards | +Assignee Lists | +
---|---|---|---|---|---|
Core | +1 | +1 | +No | +No | +No | +
Starter | +Multiple | +1 | +Yes | +No | +No | +
Premium | +Multiple | +Multiple | +Yes | +Yes | +Yes | +
Ultimate | +Multiple | +Multiple | +Yes | +Yes | +Yes | +
A few things to remember:
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+The benefits of Continuous Integration are huge when automation plays an +integral part of your workflow. GitLab comes with built-in Continuous +Integration, Continuous Deployment, and Continuous Delivery support +to build, test, and deploy your application.
+Here's some info we've gathered to get you started.
+The first steps towards your GitLab CI/CD journey.
+.gitlab-ci.yml
- Learn all about the ins and outs of .gitlab-ci.yml
..gitlab-ci.yml
or the ones defined in your project's settings
+Once you get familiar with the basics of GitLab CI/CD, it's time to dive in and +learn how to leverage its potential even more.
+Leverage the power of Docker to run your CI pipelines.
+See the documentation on GitLab Pages.
+Check the GitLab CI/CD examples for a collection of tutorials and guides on setting up your CI/CD pipeline for various programming languages, frameworks, +and operating systems.
+As a GitLab administrator, you can change the default behavior of GitLab CI/CD in +your whole GitLab instance as well as in each project.
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+++Introduced in GitLab 8.15
+
Slack slash commands allow you to control GitLab and view content right inside Slack, without having to leave it. This requires configurations in both Slack and GitLab.
+++Note: GitLab can also send events (e.g. issue created) to Slack as notifications. This is the separately configured Slack Notifications Service.
+
You can now use the Slack slash commands.
+A separate system for documentation called Wiki, is built right into each +GitLab project. It is enabled by default on all new projects and you can find +it under Wiki in your project.
+Wikis are very convenient if you don't want to keep your documentation in your +repository, but you do want to keep it in the same project where your code +resides.
+You can create Wiki pages in the web interface or +locally using Git since every Wiki is +a separate Git repository.
+++Note: +A permission level of Guest is needed to view a Wiki and +Developer is needed to create and edit Wiki pages.
+
The first time you visit a Wiki, you will be directed to create the Home page. +The Home page is necessary to be created since it serves as the landing page +when viewing a Wiki. You only have to fill in the Content section and click +Create page. You can always edit it later, so go ahead and write a welcome +message.
+ +Create a new page by clicking the New page button that can be found +in all wiki pages. You will be asked to fill in the page name from which GitLab +will create the path to the page. You can specify a full path for the new file +and any missing directories will be created automatically.
+ +Once you enter the page name, it's time to fill in its content. GitLab wikis +support Markdown, RDoc and AsciiDoc. For Markdown based pages, all the +Markdown features are supported and for links there is +some wiki specific behavior.
+++Note: +The wiki is based on a Git repository and contains only text files. Uploading +files via the web interface will upload them in GitLab itself, and they will +not be available if you clone the wiki repo locally.
+
In the web interface the commit message is optional, but the GitLab Wiki is +based on Git and needs a commit message, so one will be created for you if you +do not enter one.
+When you're ready, click the Create page and the new page will be created.
+ +To edit a page, simply click on the Edit button. From there on, you can +change its content. When done, click Save changes for the changes to take +effect.
+You can find the Delete button only when editing a page. Click on it and +confirm you want the page to be deleted.
+You can move a wiki page from one directory to another by specifying the full +path in the wiki page title in the edit form.
+ + +In order to move a wiki page to the root directory, the wiki page title must
+be preceded by the slash (/
) character.
Every wiki has a sidebar from which a short list of the created pages can be +found. The list is ordered alphabetically.
+ +If you have many pages, not all will be listed in the sidebar. Click on +More pages to see all of them.
+The changes of a wiki page over time are recorded in the wiki's Git repository, +and you can view them by clicking the Page history button.
+From the history page you can see the revision of the page (Git commit SHA), its +author, the commit message, when it was last updated and the page markup format. +To see how a previous version of the page looked like, click on a revision +number.
+ +Since wikis are based on Git repositories, you can clone them locally and edit +them like you would do with every other Git repository.
+On the right sidebar, click on Clone repository and follow the on-screen +instructions.
++Discover projects, groups and snippets. Share your projects with others +
+++Notes:
+
In your dashboard, click the green New project button or use the plus +icon in the upper right corner of the navigation bar.
+ +This opens the New project page.
+ +Choose if you want start a blank project, or with one of the predefined +Project Templates: +this will kickstart your repository code and CI automatically. +Otherwise, if you have a project in a different repository, you can import it by +clicking on the Import project tab, provided this is enabled in +your GitLab instance. Ask your administrator if not.
+Provide the following information:
+Click Create project.
+++Introduced in GitLab 10.5.
+
When you create a new repo locally, instead of going to GitLab to manually +create a new project and then push the repo, you can directly push it to +GitLab to create the new project, all without leaving your terminal. If you have access to that +namespace, we will automatically create a new project under that GitLab namespace with its +visibility set to Private by default (you can later change it in the project's settings).
+This can be done by using either SSH or HTTP:
+## Git push using SSH
+git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master
+
+## Git push using HTTP
+git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master
+Once the push finishes successfully, a remote message will indicate +the command to set the remote and the URL to the new project:
+remote:
+remote: The private project namespace/nonexistent-project was created.
+remote:
+remote: To configure the remote, run:
+remote: git remote add origin https://gitlab.example.com/namespace/nonexistent-project.git
+remote:
+remote: To view the project, visit:
+remote: https://gitlab.example.com/namespace/nonexistent-project
+remote:
++Discover projects, groups and snippets. Share your projects with others +
++Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
+In addition to the specific migration documentation above, you can import any +Git repository via HTTP from the New Project page. Be aware that if the +repository is too large the import can timeout.
+You can copy your repos by changing the remote and pushing to the new server, +but issues and merge requests can't be imported.
+If you want to retain all metadata like issues and merge requests, you can use +the import/export feature.
++Discover projects, groups and snippets. Share your projects with others +
++Manage Git repositories with fine-grained access controls that keep your code secure. +Perform code reviews and enhance collaboration with merge requests. +Each project can also have an issue tracker and a wiki. +
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+A fork is a copy of an original repository that you can put in another namespace +where you can experiment and apply changes that you can later decide if +publishing or not, without affecting your original project.
+It takes just a few steps to fork a project in GitLab.
+Go to a project's dashboard under the Project tab and click on the +Fork button.
+ +You will be asked where to fork the repository. Click on the user or group +to where you'd like to add the forked project.
+ +After a few moments, depending on the repository's size, the forking will +complete.
++Discover projects, groups and snippets. Share your projects with others +
+++Introduced in GitLab Ultimate 10.4. +Brought to GitLab Core in 10.7.
+
The Web IDE makes it faster and easier to contribute changes to your projects +by providing an advanced editor with commit staging.
+The Web IDE can be opened when viewing a file, from the repository file list, +and from merge requests.
+ +++Introduced in GitLab Core 10.8.
+
The file finder allows you to quickly open files in the current branch by
+searching. The file finder is launched using the keyboard shortcut Command-p
,
+Control-p
, or t
(when editor is not in focus). Type the filename or
+file path fragments to start seeing results.
After making your changes, click the Commit button in the bottom left to +review the list of changed files. Click on each file to review the changes and +click the tick icon to stage the file.
+Once you have staged some changes, you can add a commit message and commit the +staged changes. Unstaged changes will not be commited.
+ +Before you commit your changes, you can compare them with the previous commit +by switching to the review mode or selecting the file from the staged files +list.
+An additional review mode is available when you open a merge request, which +shows you a preview of the merge request diff if you commit your changes.
+++Introduced in GitLab Core 11.0.
+
The Web IDE can be used to quickly fix failing tests by opening the branch or +merge request in the Web IDE and opening the logs of the failed job. The status +of all jobs for the most recent pipeline and job traces for the current commit +can be accessed by clicking the Pipelines button in the top right.
+The pipeline status is also shown at all times in the status bar in the bottom +left.
+++Introduced in GitLab Core 11.0.
+
Switching between your authored and assigned merge requests can be done without +leaving the Web IDE. Click the project name in the top left to open a list of +merge requests. You will need to commit or discard all your changes before +switching to a different merge request.
++Discover projects, groups and snippets. Share your projects with others +
++Discover projects, groups and snippets. Share your projects with others +
+GitLab allows you to change your projects' visibility in order be accessed +publicly or internally.
+Projects with either of these visibility levels will be listed in the
+public access directory (/public
under your GitLab instance).
+Here is the GitLab.com example.
Internal projects will only be available to authenticated users.
+Public projects can be cloned without any authentication.
+They will also be listed on the public access directory (/public
).
Any logged in user will have Guest +permissions on the repository.
+Internal projects can be cloned by any logged in user.
+They will also be listed on the public access directory (/public
) for logged
+in users.
Any logged in user will have Guest permissions +on the repository.
+++Note: +Starting with GitLab 8.6, the group visibility has changed and can be +configured the same way as projects. In previous versions, a group's page was +always visible to all users.
+
Like with projects, the visibility of a group can be set to dictate whether +anonymous users, all signed in users, or only explicit group members can view +it. The restriction for visibility levels on the application setting level also +applies to groups, so if that's set to internal, the explore page will be empty +for anonymous users. The group page now has a visibility level icon.
+The public page of a user, located at /username
, is always visible whether
+you are logged in or not.
When visiting the public page of a user, you can only see the projects which +you are privileged to.
+If the public level is restricted, user profiles are only visible to logged in users.
+In the Admin area under Settings (/admin/application_settings
), you can
+restrict the use of visibility levels for users when they create a project or a
+snippet:
This is useful to prevent people exposing their repositories to public +by accident. The restricted visibility settings do not apply to admin users.
+