diff options
Diffstat (limited to 'doc/user/project')
148 files changed, 2993 insertions, 43 deletions
diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md new file mode 100644 index 00000000000..cce862b0911 --- /dev/null +++ b/doc/user/project/canary_deployments.md @@ -0,0 +1,71 @@ +# Canary Deployments **[PREMIUM]** + +> [Introduced][ee-1659] in [GitLab Premium][eep] 9.1. + +A popular [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) +strategy, where a small portion of the fleet is updated to the new version of +your application. + +## Overview + +When embracing [Continuous Delivery][cd-blog], a company needs to decide what +type of deployment strategy to use. One of the most popular strategies is canary +deployments, where a small portion of the fleet is updated to the new version +first. This subset, the canaries, then serve as the proverbial +[canary in the coal mine](https://en.wiktionary.org/wiki/canary_in_a_coal_mine). + +If there is a problem with the new version of the application, only a small +percentage of users are affected and the change can either be fixed or quickly +reverted. + +Leveraging [Kubernetes' Canary deployments][kube-canary], visualize your canary +deployments right inside the [Deploy Board], without the need to leave GitLab. + +## Use cases + +Canary deployments can be used when you want to ship features to only a portion of +your pods fleet and watch their behavior as a percentage of your user base +visits the temporarily deployed feature. If all works well, you can deploy the +feature to production knowing that it won't cause any problems. + +Canary deployments are also especially useful for backend refactors, performance +improvements, or other changes where the user interface doesn't change, but you +want to make sure the performance stays the same, or improves. Developers need +to be careful when using canaries with user-facing changes, because by default, +requests from the same user will be randomly distributed between canary and +non-canary pods, which could result in confusion or even errors. If needed, you +may want to consider [setting `service.spec.sessionAffinity` to `ClientIP` in +your Kubernetes service definitions][kube-net], but that is beyond the scope of +this document. + +## Enabling Canary Deployments + +Canary deployments require that you properly configure Deploy Boards: + +1. Follow the steps to [enable Deploy Boards](deploy_boards.md#enabling-deploy-boards). +1. To track canary deployments you need to label your Kubernetes deployments and + pods with `track: canary`. To get started quickly, you can use the [Auto Deploy] + template for canary deployments that GitLab provides. + +Depending on the deploy, the label should be either `stable` or `canary`. +Usually, `stable` and blank or missing label means the same thing, and `canary` +or any other track means canary/temporary. +This allows GitLab to discover whether deployment is stable or canary (temporary). + +Once all of the above are set up and the pipeline has run at least once, +navigate to the environments page under **Pipelines > Environments**. +As the pipeline executes Deploy Boards will clearly mark canary pods, enabling +quick and easy insight into the status of each environment and deployment. + +Canary deployments are marked with a yellow dot in the Deploy Board so that you +can easily notice them. + + + +[autodeploy]: ../../ci/autodeploy/index.md "GitLab Autodeploy" +[eep]: https://about.gitlab.com/pricing/ +[ee-1659]: https://gitlab.com/gitlab-org/gitlab-ee/issues/1659 +[kube-canary]: https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments +[deploy board]: deploy_boards.md +[cd-blog]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/ +[kube-net]: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies diff --git a/doc/user/project/ci_cd_for_external_repo.md b/doc/user/project/ci_cd_for_external_repo.md new file mode 100644 index 00000000000..a92d3a2c308 --- /dev/null +++ b/doc/user/project/ci_cd_for_external_repo.md @@ -0,0 +1,5 @@ +--- +redirect_to: '../../ci/ci_cd_for_external_repos/index.md' +--- + +This document was moved to [another location](../../ci/ci_cd_for_external_repos/index.md). diff --git a/doc/user/project/clusters/img/k8s_cluster_monitoring.png b/doc/user/project/clusters/img/k8s_cluster_monitoring.png Binary files differnew file mode 100644 index 00000000000..d0adec4520f --- /dev/null +++ b/doc/user/project/clusters/img/k8s_cluster_monitoring.png diff --git a/doc/user/project/clusters/img/kubernetes_pod_logs.png b/doc/user/project/clusters/img/kubernetes_pod_logs.png Binary files differnew file mode 100644 index 00000000000..e664a47386a --- /dev/null +++ b/doc/user/project/clusters/img/kubernetes_pod_logs.png diff --git a/doc/user/project/clusters/img/pod_logs_deploy_board.png b/doc/user/project/clusters/img/pod_logs_deploy_board.png Binary files differnew file mode 100644 index 00000000000..7f83382968b --- /dev/null +++ b/doc/user/project/clusters/img/pod_logs_deploy_board.png diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index e84c3ca4bef..81e7ad4d5ac 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -479,7 +479,7 @@ differentiate the new cluster with the rest. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments.md) similar to how the -[environment-specific variables](https://docs.gitlab.com/ee/ci/variables/README.html#limiting-environment-scopes-of-variables-premium) work. +[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-variables-premium) 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 @@ -576,7 +576,7 @@ credentials. When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. - + ## Enabling or disabling the Kubernetes cluster integration @@ -607,7 +607,7 @@ and add a Kubernetes cluster again. ## View Kubernetes pod logs from GitLab **[ULTIMATE]** Learn how to easily -[view the logs of running pods in connected Kubernetes clusters](https://docs.gitlab.com/ee/user/project/clusters/kubernetes_pod_logs.html). +[view the logs of running pods in connected Kubernetes clusters](kubernetes_pod_logs.md). ## What you can get with the Kubernetes integration @@ -621,7 +621,7 @@ 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](https://docs.gitlab.com/ee/user/project/deploy_boards.html) +[Read more about Deploy Boards](../deploy_boards.md) ### Canary Deployments **[PREMIUM]** @@ -629,7 +629,7 @@ Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cl and visualize your canary deployments right inside the Deploy Board, without the need to leave GitLab. -[Read more about Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) +[Read more about Canary Deployments](../canary_deployments.md) ### Kubernetes monitoring diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md new file mode 100644 index 00000000000..e0815b5b553 --- /dev/null +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -0,0 +1,32 @@ +# Kubernetes Pod Logs **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. + +GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md). +By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface. + +## Overview + +[Kubernetes](https://kubernetes.io) pod logs can be viewed directly within GitLab. Logs can be displayed by clicking on a specific pod from [Deploy Boards](../deploy_boards.md): + +1. Go to **Operations > Environments** and find the environment which contains the desired pod, like `production`. +1. On the **Environments** page, you should see the status of the environment's pods with [Deploy Boards](../deploy_boards.md). +1. When mousing over the list of pods, a tooltip will appear with the exact pod name and status. + +1. Click on the desired pod to bring up the logs view, which will contain the last 500 lines for that pod. Support for pods with multiple containers is coming [in a future release](https://gitlab.com/gitlab-org/gitlab-ee/issues/6502). + + +## Requirements + +There are a few key requirements in order to be able to use Pod Logs: + +1. [Create or connect a Kubernetes cluster to the project](index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) +1. A GitLab Runner. If one is not available, they can be easily [deployed](index.md#installing-applications). +1. Ensure a Kubernetes label of `app: $CI_ENVIRONMENT_SLUG` is applied to the + deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` is the value + of the [CI variable](../../../ci/variables/README.md#predefined-environment-variables). + This needed to determine the environment a pod belongs to + when is more than one. These resources should be + contained in the namespace defined in the Kubernetes service setting. + The [Auto DevOps](../../../topics/autodevops/index.md) `.gitlab-ci.yml` template has predefined + stages and commands to use, and automatically applies the labeling. diff --git a/doc/user/project/clusters/runbooks/img/authorize-jupyter.png b/doc/user/project/clusters/runbooks/img/authorize-jupyter.png Binary files differindex 84cce311483..f3e868de802 100644 --- a/doc/user/project/clusters/runbooks/img/authorize-jupyter.png +++ b/doc/user/project/clusters/runbooks/img/authorize-jupyter.png diff --git a/doc/user/project/clusters/runbooks/img/gitlab-variables.png b/doc/user/project/clusters/runbooks/img/gitlab-variables.png Binary files differindex 1d338f063a9..7c9c9099851 100644 --- a/doc/user/project/clusters/runbooks/img/gitlab-variables.png +++ b/doc/user/project/clusters/runbooks/img/gitlab-variables.png diff --git a/doc/user/project/clusters/runbooks/img/helm-install.png b/doc/user/project/clusters/runbooks/img/helm-install.png Binary files differindex 003e482e756..e67cf317ec1 100644 --- a/doc/user/project/clusters/runbooks/img/helm-install.png +++ b/doc/user/project/clusters/runbooks/img/helm-install.png diff --git a/doc/user/project/clusters/runbooks/img/ingress-install.png b/doc/user/project/clusters/runbooks/img/ingress-install.png Binary files differindex 7edc11d5b45..08256a65138 100644 --- a/doc/user/project/clusters/runbooks/img/ingress-install.png +++ b/doc/user/project/clusters/runbooks/img/ingress-install.png diff --git a/doc/user/project/clusters/runbooks/img/jupyterhub-install.png b/doc/user/project/clusters/runbooks/img/jupyterhub-install.png Binary files differindex 75c6028a763..784e508ff25 100644 --- a/doc/user/project/clusters/runbooks/img/jupyterhub-install.png +++ b/doc/user/project/clusters/runbooks/img/jupyterhub-install.png diff --git a/doc/user/project/clusters/runbooks/img/postgres-query.png b/doc/user/project/clusters/runbooks/img/postgres-query.png Binary files differindex 04315d54d5e..dbb5a62ebba 100644 --- a/doc/user/project/clusters/runbooks/img/postgres-query.png +++ b/doc/user/project/clusters/runbooks/img/postgres-query.png diff --git a/doc/user/project/clusters/runbooks/img/sample-runbook.png b/doc/user/project/clusters/runbooks/img/sample-runbook.png Binary files differindex 70011202bf0..545d34fd4ad 100644 --- a/doc/user/project/clusters/runbooks/img/sample-runbook.png +++ b/doc/user/project/clusters/runbooks/img/sample-runbook.png diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md new file mode 100644 index 00000000000..a4937e6cf6b --- /dev/null +++ b/doc/user/project/code_owners.md @@ -0,0 +1,85 @@ +# Code Owners **[STARTER]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6916) +in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. + +You can use a `CODEOWNERS` file to specify users that are responsible +for certain files in a repository. + +You can choose and add the `CODEOWNERS` file in three places: + +- to the root directory of the repository +- inside the `.gitlab/` directory +- inside the `docs/` directory + +The `CODEOWNERS` file is scoped to a branch, which means that with the +introduction of new files, the person adding the new content can +specify themselves as a code owner, all before the new changes +get merged to the default branch. + +When a file matches multiple entries in the `CODEOWNERS` file, +the users from all entries are displayed on the blob page of +the given file. + +## The syntax of Code Owners files + +Files can be specified using the same kind of patterns you would use +in the `.gitignore` file followed by the `@username` or email of one +or more users that should be owners of the file. + +The order in which the paths are defined is significant: the last +pattern that matches a given path will be used to find the code +owners. + +Starting a line with a `#` indicates a comment. This needs to be +escaped using `\#` to address files for which the name starts with a +`#`. + +Example `CODEOWNERS` file: + +``` +# This is an example code owners file, lines starting with a `#` will +# be ignored. + +# app/ @commented-rule + +# We can specifiy a default match using wildcards: +* @default-codeowner + +# Rules defined later in the file take precedence over the rules +# defined before. +# This will match all files for which the file name ends in `.rb` +*.rb @ruby-owner + +# Files with a `#` can still be accesssed by escaping the pound sign +\#file_with_pound.rb @owner-file-with-pound + +# Multiple codeowners can be specified, separated by whitespace +CODEOWNERS @multiple @owners @tab-separated + +# Both usernames or email addresses can be used to match +# users. Everything else will be ignored. For example this will +# specify `@legal` and a user with email `janedoe@gitlab.com` as the +# owner for the LICENSE file +LICENSE @legal this_does_not_match janedoe@gitlab.com + +# Ending a path in a `/` will specify the code owners for every file +# nested in that directory, on any level +/docs/ @all-docs + +# Ending a path in `/*` will specify code owners for every file in +# that directory, but not nested deeper. This will match +# `docs/index.md` but not `docs/projects/index.md` +/docs/* @root-docs + +# This will make a `lib` directory nested anywhere in the repository +# match +lib/ @lib-owner + +# This will only match a `config` directory in the root of the +# repository +/config/ @config-owner + +# If the path contains spaces, these need to be escaped like this: +path\ with\ spaces/ @space-owner +``` diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md new file mode 100644 index 00000000000..01fb14f1e66 --- /dev/null +++ b/doc/user/project/deploy_boards.md @@ -0,0 +1,127 @@ +# Deploy Boards **[PREMIUM]** + +> [Introduced][ee-1589] in [GitLab Premium][ee] 9.0. + +GitLab's Deploy Boards offer a consolidated view of the current health and +status of each CI [environment] running on [Kubernetes], displaying the status +of the pods in the deployment. Developers and other teammates can view the +progress and status of a rollout, pod by pod, in the workflow they already use +without any need to access Kubernetes. + +## Overview + +With Deploy Boards you can gain more insight into deploys with benefits such as: + +- Following a deploy from the start, not just when it's done +- Watching the rollout of a build across multiple servers +- Finer state detail (Waiting, Deploying, Finished, Unknown) +- See [Canary Deployments](canary_deployments.md) + +Here's an example of a Deploy Board of the production environment. + + + +The squares represent pods in your Kubernetes cluster that are associated with +the given environment. Hovering above each square you can see the state of a +deploy rolling out. The percentage is the percent of the pods that are updated +to the latest release. + +Since Deploy Boards are tightly coupled with Kubernetes, there is some required +knowledge. In particular you should be familiar with: + +- [Kubernetes pods](https://kubernetes.io/docs/user-guide/pods) +- [Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) +- [Kubernetes namespaces](https://kubernetes.io/docs/user-guide/namespaces/) +- [Kubernetes canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) + +## Use cases + +Since the Deploy Board is a visual representation of the Kubernetes pods for a +specific environment, there are lot of uses cases. To name a few: + +- You want to promote what's running in staging, to production. You go to the + environments list, verify that what's running in staging is what you think is + running, then click on the [manual action] to deploy to production. +- You trigger a deploy, and you've got lots of containers to upgrade so you know + it'll take a while (you've also throttled your deploy to only take down X + containers at a time). But you need to tell someone when it's deployed, so you + go to the environments list, look at the production environment to see what + the progress is in real-time as each pod is rolled. +- You get a report that something is weird in production, so you look at the + production environment to see what is running, and if a deploy is ongoing or + stuck or failed. +- You've got an MR that looks good, but you want to run it on staging because + staging is set up in some way closer to production. You go to the environment + list, find the [Review App][review apps] you're interested in, and click the + manual action to deploy it to staging. + +## Enabling Deploy Boards + +To display the Deploy Boards for a specific [environment] you should: + +1. Have a Kubernetes cluster up and running. + + NOTE: **Running on OpenShift:** + If you are using OpenShift, ensure that you're using the `Deployment` resource + instead of `DeploymentConfiguration`, otherwise the Deploy Boards won't render + correctly. For more information, read the + [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) + and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab-ee/issues/4584). + +1. [Configure GitLab Runner][runners] with the [Docker][docker-exec] or + [Kubernetes][kube-exec] executor. +1. Configure the [Kubernetes service][kube-service] in your project for the + cluster. The Kubernetes namespace is of particular note as you will need it + for your deployment scripts (exposed by the `KUBE_NAMESPACE` env variable). +1. Ensure a Kubernetes label of `app: $CI_ENVIRONMENT_SLUG` is applied to the + deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` the value + of the CI variable. This is so we can lookup the proper environment in a + cluster/namespace which may have more than one. These resources should be + contained in the namespace defined in the Kubernetes service setting. + You can use an [Autodeploy] `.gitlab-ci.yml` template which has predefined + stages and commands to use, and automatically applies the labeling. + Each project will need to have a unique namespace in Kubernetes as well. + The image below demonstrates how this is shown inside Kubernetes. + +  + +Once all of the above are set up and the pipeline has run at least once, +navigate to the environments page under **Operations > Environments**. + +Deploy Boards are visible by default. You can explicitly click +the triangle next to their respective environment name in order to hide them. +GitLab will then query Kubernetes for the state of each node (e.g., waiting, +deploying, finished, unknown), and the Deploy Board status will finally appear. + +GitLab will only display a Deploy Board for top-level environments. Foldered +environments like `review/*` (usually used for [Review Apps]) won't have a +Deploy Board attached to them. + +## Canary Deployments + +A popular CI strategy, where a small portion of the fleet is updated to the new +version of your application. + +[Read more about Canary Deployments.](canary_deployments.md) + +## Further reading + +- [GitLab Autodeploy][autodeploy] +- [GitLab CI environment variables][variables] +- [Environments and deployments][environment] +- [Kubernetes deploy example][kube-deploy] + +[ee-1589]: https://gitlab.com/gitlab-org/gitlab-ee/issues/1589 "Deploy Boards initial issue" +[ee]: https://about.gitlab.com/pricing/ "GitLab Enterprise Edition landing page" +[kube-deploy]: https://gitlab.com/gitlab-examples/kubernetes-deploy "Kubernetes deploy example project" +[kubernetes]: https://kubernetes.io "Kubernetes website" +[environment]: ../../ci/environments.md "Environments and deployments documentation" +[docker-exec]: https://docs.gitlab.com/runner/executors/docker.html "GitLab Runner Docker executor" +[kube-exec]: https://docs.gitlab.com/runner/executors/kubernetes.html "GitLab Runner Kubernetes executor" +[kube-service]: integrations/kubernetes.md "Kubernetes project service" +[review apps]: ../../ci/review_apps/index.md "Review Apps documentation" +[variables]: ../../ci/variables/README.md "GitLab CI variables" +[autodeploy]: ../../ci/autodeploy/index.md "GitLab Autodeploy" +[kube-image]: https://gitlab.com/gitlab-examples/kubernetes-deploy/container_registry "Kubernetes deploy Container Registry" +[manual action]: ../../ci/yaml/README.md#manual-actions +[runners]: ../../ci/runners/README.md diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 08647caaf07..e230444fa67 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -2,8 +2,12 @@ >[Introduced][ce-4981] in GitLab 8.11. +We all know that a properly submitted issue is more likely to be addressed in +a timely manner by the developers of a project. + Description templates allow you to define context-specific templates for issue -and merge request description fields for your project. +and merge request description fields for your project, as well as help filter +out a lot of unnecessary noise from issues. ## Overview @@ -18,6 +22,18 @@ Description templates must be written in [Markdown](../markdown.md) and stored in your project's repository under a directory named `.gitlab`. Only the templates of the default branch will be taken into account. +## Use-cases + +- Add a template to be used in every issue for a specific project, +giving instructions and guidelines, requiring for information specific to that subject. +For example, if you have a project for tracking new blog posts, you can require the +title, outlines, author name, author social media information, etc. +- Following the previous example, you can make a template for every MR submitted +with a new blog post, requiring information about the post date, frontmatter data, +images guidelines, link to the related issue, reviewer name, etc. +- You can also create issues and merge request templates for different +stages of your workflow, e.g., feature proposal, feature improvement, bug report, etc. + ## Creating issue templates Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/` @@ -39,6 +55,32 @@ changes you made after picking the template and return it to its initial status.  +## Setting a default template for issues and merge requests **[STARTER]** + +> **Notes:** +> - This feature was introduced before [description templates](#overview) and is +> available in [GitLab Starter][products]. It can be enabled +> in the project's settings. +> - Templates for issues were [introduced][ee-28] in GitLab EE 8.1. +> - Templates for merge requests were [introduced][ee-7478ece] in GitLab EE 6.9. + +The visibility of issues and/or merge requests should be set to either "Everyone +with access" or "Only team members" in your project's **Settings** otherwise the +template text areas won't show. This is the default behavior so in most cases +you should be fine. + +Go to your project's **Settings** and fill in the "Default description template +for issues" and "Default description template for merge requests" text areas +for issues and merge requests respectively. Since GitLab issues and merge +request support [Markdown](../markdown.md), you can use special markup like +headings, lists, etc. + + + +After you add the description, hit **Save changes** for the settings to take +effect. Now, every time a new issue or merge request is created, it will be +pre-filled with the text you entered in the template(s). + ## Description template example We make use of Description Templates for Issues and Merge Requests within the GitLab Community Edition project. Please refer to the [`.gitlab` folder][gitlab-ce-templates] for some examples. @@ -93,3 +135,6 @@ Possible fixes [ce-4981]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4981 [gitlab-ce-templates]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/.gitlab +[ee-28]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/28 "Merge Request for adding issues template" +[ee-7478ece]: https://gitlab.com/gitlab-org/gitlab-ee/commit/7478ece8b48e80782b5465b96c79f85cc91d391b "Commit that introduced merge requests templates" +[products]: https://about.gitlab.com/pricing/ diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md new file mode 100644 index 00000000000..541023692ea --- /dev/null +++ b/doc/user/project/file_lock.md @@ -0,0 +1,107 @@ +# File Locking **[PREMIUM]** + +> **Notes:** +> - [Introduced][ee-440] in [GitLab Premium][ee] 8.9. +> - This feature needs to have a license with the "File Lock" option enabled. If +> you are using Premium but you don't see the "Lock" button, +> ask your GitLab administrator. + +File Locking helps you avoid merge conflicts and better manage your binary files. +Lock any file or directory, make your changes, and then unlock it so another +member of the team can edit it. + +## Overview + +Working with multiple people on the same file can be a risk. Conflicts +when merging a non-text file are hard to overcome and will require a lot +of manual work to resolve. With GitLab Premium, File +Locking helps you avoid merge conflicts and better manage your binary +files by preventing everyone, except you, from modifying a specific file +or entire directory. + +## Use-cases + +The file locking feature is useful in situations when: + +- Multiple people are working on the same file and you want to avoid merge + conflicts. +- Your repository contains binary files in which situation there is no easy + way to tell the diff between yours and your colleagues' changes. +- Prevent design assets from being overwritten. + +Locked directories are locked recursively, which means that everything that +lies under them is also locked. + +## Permissions on file locking + +The user that locks a file or directory **is the only one** that can edit and +push their changes back to the repository where the locked objects are located. + +Locks can be created by any person who has [push access] to the repository; i.e., +Developer and higher level, and can be removed solely by their author and any +user with Maintainer permissions and above. + +If a file is locked and you are not the author of its locked state, a +pre-receive hook will reject your changes when you try to push. In the +following example, a user who has no permissions on the locked `.gitignore` +file will see the message below: + +```bash +Counting objects: 3, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (3/3), done. +Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done. +Total 3 (delta 1), reused 0 (delta 0) +remote: GitLab: The path '.gitignore' is locked by Administrator +To https://example.com/gitlab-org/gitlab-ce.git + ! [remote rejected] master -> master (pre-receive hook declined) + error: failed to push some refs to 'https://example.com/gitlab-org/gitlab-ce.git' +``` + +Similarly, when a user that is not the author of the locked state of a file +accepts a merge request, an error message will appear stating that the file +is locked. + + + +## Locking a file or a directory + +>**Note:** +Locking only works for the default branch you have set in the project's settings +(usually `master`). + +To lock a file, navigate to the repository tree under the **Repository > Files** tab, +pick the file you want to lock and hit the "Lock" button. + + + +--- + +To lock an entire directory, look for the "Lock" link next to "History". + + + +--- + +After you lock a file or directory, it will appear as locked in the repository +view. + + + +## Unlocking a file or a directory + +To unlock a file or a directory, follow the same procedure as when you locked +them. For a detailed view of every existing lock, see the next section on +"Viewing and managing existing locks". + +## Viewing and managing existing locks + +To view or manage every existing lock, navigate to the +**Project > Repository > Locked Files** area. There, you can view all existing +locks and [remove the ones you have permission for](#permissions-on-file-locking). + + + +[ee-440]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/440 "File Lock" +[ee]: https://about.gitlab.com/pricing/ +[push access]: ../../user/permissions.md diff --git a/doc/user/project/img/assignee_lists.png b/doc/user/project/img/assignee_lists.png Binary files differnew file mode 100644 index 00000000000..f2660cd8f80 --- /dev/null +++ b/doc/user/project/img/assignee_lists.png diff --git a/doc/user/project/img/deploy_boards_canary_deployments.png b/doc/user/project/img/deploy_boards_canary_deployments.png Binary files differnew file mode 100644 index 00000000000..037b4a908ab --- /dev/null +++ b/doc/user/project/img/deploy_boards_canary_deployments.png diff --git a/doc/user/project/img/deploy_boards_kubernetes_label.png b/doc/user/project/img/deploy_boards_kubernetes_label.png Binary files differnew file mode 100644 index 00000000000..c6d90dc92df --- /dev/null +++ b/doc/user/project/img/deploy_boards_kubernetes_label.png diff --git a/doc/user/project/img/deploy_boards_landing_page.png b/doc/user/project/img/deploy_boards_landing_page.png Binary files differnew file mode 100644 index 00000000000..c9621a06860 --- /dev/null +++ b/doc/user/project/img/deploy_boards_landing_page.png diff --git a/doc/user/project/img/description_templates_default_settings.png b/doc/user/project/img/description_templates_default_settings.png Binary files differnew file mode 100644 index 00000000000..ab314e83d06 --- /dev/null +++ b/doc/user/project/img/description_templates_default_settings.png diff --git a/doc/user/project/img/file_lock.png b/doc/user/project/img/file_lock.png Binary files differnew file mode 100644 index 00000000000..33f96f20e91 --- /dev/null +++ b/doc/user/project/img/file_lock.png diff --git a/doc/user/project/img/file_lock_folders.png b/doc/user/project/img/file_lock_folders.png Binary files differnew file mode 100644 index 00000000000..5ff3d4d9dbd --- /dev/null +++ b/doc/user/project/img/file_lock_folders.png diff --git a/doc/user/project/img/file_lock_list.png b/doc/user/project/img/file_lock_list.png Binary files differnew file mode 100644 index 00000000000..2c276335c83 --- /dev/null +++ b/doc/user/project/img/file_lock_list.png diff --git a/doc/user/project/img/file_lock_merge_request_error_message.png b/doc/user/project/img/file_lock_merge_request_error_message.png Binary files differnew file mode 100644 index 00000000000..65bc3692da0 --- /dev/null +++ b/doc/user/project/img/file_lock_merge_request_error_message.png diff --git a/doc/user/project/img/file_lock_repository_view.png b/doc/user/project/img/file_lock_repository_view.png Binary files differnew file mode 100644 index 00000000000..8f4ef52aacd --- /dev/null +++ b/doc/user/project/img/file_lock_repository_view.png diff --git a/doc/user/project/img/labels_default.png b/doc/user/project/img/labels_default.png Binary files differindex 7a7fab611a4..221c5cf55a2 100644 --- a/doc/user/project/img/labels_default.png +++ b/doc/user/project/img/labels_default.png diff --git a/doc/user/project/img/labels_epic_sidebar.png b/doc/user/project/img/labels_epic_sidebar.png Binary files differnew file mode 100644 index 00000000000..f8162d89e9d --- /dev/null +++ b/doc/user/project/img/labels_epic_sidebar.png diff --git a/doc/user/project/img/labels_list.png b/doc/user/project/img/labels_list.png Binary files differindex 6878349fc0c..6940dde68bf 100644 --- a/doc/user/project/img/labels_list.png +++ b/doc/user/project/img/labels_list.png diff --git a/doc/user/project/img/project_security_dashboard.png b/doc/user/project/img/project_security_dashboard.png Binary files differnew file mode 100644 index 00000000000..3294e59e943 --- /dev/null +++ b/doc/user/project/img/project_security_dashboard.png diff --git a/doc/user/project/img/protected_branches_select_roles_and_users.png b/doc/user/project/img/protected_branches_select_roles_and_users.png Binary files differnew file mode 100644 index 00000000000..4f62b057cc7 --- /dev/null +++ b/doc/user/project/img/protected_branches_select_roles_and_users.png diff --git a/doc/user/project/img/protected_branches_select_roles_and_users_list.png b/doc/user/project/img/protected_branches_select_roles_and_users_list.png Binary files differnew file mode 100644 index 00000000000..519f2267496 --- /dev/null +++ b/doc/user/project/img/protected_branches_select_roles_and_users_list.png diff --git a/doc/user/project/img/service_desk_confirmation_email.png b/doc/user/project/img/service_desk_confirmation_email.png Binary files differnew file mode 100644 index 00000000000..e08dced1e38 --- /dev/null +++ b/doc/user/project/img/service_desk_confirmation_email.png diff --git a/doc/user/project/img/service_desk_disabled.png b/doc/user/project/img/service_desk_disabled.png Binary files differnew file mode 100644 index 00000000000..3ae64dcbe96 --- /dev/null +++ b/doc/user/project/img/service_desk_disabled.png diff --git a/doc/user/project/img/service_desk_enabled.png b/doc/user/project/img/service_desk_enabled.png Binary files differnew file mode 100644 index 00000000000..329348e4b52 --- /dev/null +++ b/doc/user/project/img/service_desk_enabled.png diff --git a/doc/user/project/img/service_desk_issue_tracker.png b/doc/user/project/img/service_desk_issue_tracker.png Binary files differnew file mode 100644 index 00000000000..485751fab0a --- /dev/null +++ b/doc/user/project/img/service_desk_issue_tracker.png diff --git a/doc/user/project/img/service_desk_nav_item.png b/doc/user/project/img/service_desk_nav_item.png Binary files differnew file mode 100644 index 00000000000..3420e355f67 --- /dev/null +++ b/doc/user/project/img/service_desk_nav_item.png diff --git a/doc/user/project/img/service_desk_reply.png b/doc/user/project/img/service_desk_reply.png Binary files differnew file mode 100644 index 00000000000..ae6ce31713b --- /dev/null +++ b/doc/user/project/img/service_desk_reply.png diff --git a/doc/user/project/img/service_desk_thread.png b/doc/user/project/img/service_desk_thread.png Binary files differnew file mode 100644 index 00000000000..8d8ac39cc5b --- /dev/null +++ b/doc/user/project/img/service_desk_thread.png diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md new file mode 100644 index 00000000000..664c50e0494 --- /dev/null +++ b/doc/user/project/import/gemnasium.md @@ -0,0 +1,102 @@ +# Gemnasium **[ULTIMATE]** + +This guide describes how to migrate from Gemnasium.com to your own GitLab +instance or GitLab.com. + +## Why is Gemnasium.com closed? + +Gemnasium has been [acquired by GitLab](https://about.gitlab.com/press/releases/2018-01-30-gemnasium-acquisition.html) +in January 2018. Since May 15, 2018, the services provided by Gemnasium are no longer available. +The team behind Gemnasium has joined GitLab as the new Security Products team +and is working on a wider range of tools than just Dependency Scanning: +[SAST](../merge_requests/sast.md), +[DAST](../merge_requests/dast.md), +[Container Scanning](../merge_requests/container_scanning.md) and more. +If you want to continue monitoring your dependencies, see the +[Migrating to GitLab](#migrating-to-gitlab) section below. + +## What happened to my account? + +Your account has been automatically closed on May 15th, 2018. If you had a paid +subscription at that time, your card will be refunded on a pro rata temporis basis. +You may contact `gemnasium@gitlab.com` regarding your closed account. + +## Will my account/data be transferred to GitLab Inc.? + +All accounts and data have been deleted on May 15th, 2018. GitLab Inc. +doesn't know anything about your private data, nor your projects, and therefore +if they were vulnerable or not. GitLab Inc. takes personal information very seriously. + +## What happened to my badge? + +To avoid broken 404 images, all badges pointing to Gemnasium.com will be a +placeholder, inviting you to migrate to GitLab (and pointing to this page). + +## Migrating to GitLab + +Gemnasium has been ported and integrated directly into GitLab CI/CD. +You can still benefit from our dependency monitoring features, and it requires +some steps to migrate your projects. There is no automatic import since GitLab +doesn't know anything about any projects which existed on Gemnasium.com. +Security features are free for public (open-source) projects hosted on GitLab.com. + +### If your project is hosted on GitLab (https://gitlab.com / self-hosted) + +You're almost set! If you're already using +[Auto DevOps](../../../topics/autodevops/), you are already covered. +Otherwise, you must configure your `.gitlab-ci.yml` according to the +[dependency scanning page](../merge_requests/dependency_scanning.md). + +### If your project is hosted on GitHub (https://github.com / GitHub Enterprise) + +Since [GitLab 10.6 comes with GitHub integration](https://about.gitlab.com/features/github/), +GitLab users can now create a CI/CD project in GitLab connected to an external +GitHub.com or GitHub Enterprise repository. This will automatically prompt +GitLab CI/CD to run whenever code is pushed to GitHub and post CI/CD results +back to both GitLab and GitHub when completed. + +1. Create a new project, and select the "CI/CD for external repo" tab: + +  + +1. Use the "GitHub" button to connect your repositories. + +  + +1. Select the project(s) to be set up with GitLab CI/CD and chose "Connect". + +  + + Once the configuration is done, you may click on your new + project on GitLab. + +  + + Your project is now mirrored on GitLab, where the Runners will be able to access + your source code and run your tests. + + Optional step: If you set this up on GitLab.com, make sure the project is + public (in the project settings) if your GitHub project is public, since + the security feature is available only for [GitLab Ultimate](https://about.gitlab.com/pricing). + +1. To set up the dependency scanning job, corresponding to what Gemnasium was + doing, you must create a `.gitlab-ci.yml` file, or update it according to + the [dependency scanning docs](../merge_requests/dependency_scanning.md). + The mirroring is pull-only by default, so you may create or update the file on + GitHub: + +  + +1. Once your file has been committed, a new pipeline will be automatically + triggered if your file is valid: + +  + +1. The result of the job will be visible directly from the pipeline view: + +  + +NOTE: **Note:** +If you don't commit very often to your project, you may want to use +[scheduled pipelines](../pipelines/schedules.md) to run the job on a regular +basis. diff --git a/doc/user/project/import/img/gemnasium/connect_github.png b/doc/user/project/import/img/gemnasium/connect_github.png Binary files differnew file mode 100644 index 00000000000..5933f4d5d0a --- /dev/null +++ b/doc/user/project/import/img/gemnasium/connect_github.png diff --git a/doc/user/project/import/img/gemnasium/create_project.png b/doc/user/project/import/img/gemnasium/create_project.png Binary files differnew file mode 100644 index 00000000000..6e00bf63405 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/create_project.png diff --git a/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png b/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png Binary files differnew file mode 100644 index 00000000000..8336c803b83 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png diff --git a/doc/user/project/import/img/gemnasium/pipeline.png b/doc/user/project/import/img/gemnasium/pipeline.png Binary files differnew file mode 100644 index 00000000000..ae4d5295ffa --- /dev/null +++ b/doc/user/project/import/img/gemnasium/pipeline.png diff --git a/doc/user/project/import/img/gemnasium/project_connected.png b/doc/user/project/import/img/gemnasium/project_connected.png Binary files differnew file mode 100644 index 00000000000..8e7216c015b --- /dev/null +++ b/doc/user/project/import/img/gemnasium/project_connected.png diff --git a/doc/user/project/import/img/gemnasium/report.png b/doc/user/project/import/img/gemnasium/report.png Binary files differnew file mode 100644 index 00000000000..5c4d58662c0 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/report.png diff --git a/doc/user/project/import/img/gemnasium/select_project.png b/doc/user/project/import/img/gemnasium/select_project.png Binary files differnew file mode 100644 index 00000000000..588c5ca7ce1 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/select_project.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index ca02e4e9e96..50dc3df77a6 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -13,11 +13,14 @@ 1. [From TFS](tfs.md) 1. [From repo by URL](repo_by_url.md) 1. [By uploading a manifest file (AOSP)](manifest.md) +1. [From Gemnasium](gemnasium.md) 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. +There is also the option of [connecting your external repository to get CI/CD benefits](../ci_cd_for_external_repo.md). + ## Migrating from self-hosted GitLab to GitLab.com You can copy your repos by changing the remote and pushing to the new server, diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 4148310dc98..cea1f3b37c4 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -13,7 +13,7 @@ the number of private projects you create. When you create a project in GitLab, you'll have access to a large number of [features](https://about.gitlab.com/features/): -**Issues and merge requests:** +**Repositories:** - [Issue tracker](issues/index.md): Discuss implementations with your team within issues - [Issue Boards](issue_board.md): Organize and prioritize your workflow @@ -28,6 +28,13 @@ When you create a project in GitLab, you'll have access to a large number of permission to create tags, and prevent accidental update or deletion - [Signing commits](gpg_signed_commits/index.md): use GPG to sign your commits - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. +- [Web IDE](web_ide/index.md) + +**Issues and merge requests:** + +- [Issue tracker](issues/index.md): Discuss implementations with your team within issues + - [Issue Boards](issue_board.md): Organize and prioritize your workflow + - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project **[STARTER]** - [Merge Requests](merge_requests/index.md): Apply your branching strategy and get reviewed by your team - [Merge Request Approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html): Ask for approval before @@ -67,6 +74,8 @@ When you create a project in GitLab, you'll have access to a large number of timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more - [Kubernetes cluster integration](clusters/index.md): Connecting your GitLab project with a Kubernetes cluster + - [Feature Flags](operations/feature_flags.md): Feature flags allow you to ship a project in + different flavors by dynamically toggling certain functionality **[PREMIUM]** - [GitLab Pages](pages/index.md): Build, test, and deploy your static website with GitLab Pages @@ -75,12 +84,17 @@ When you create a project in GitLab, you'll have access to a large number of - [Wiki](wiki/index.md): document your GitLab project in an integrated Wiki. - [Snippets](../snippets.md): store, share and collaborate on code snippets. - [Cycle Analytics](cycle_analytics.md): review your development lifecycle. +- [Security Dashboard](security_dashboard.md): Security Dashboard. - [Syntax highlighting](highlighting.md): an alternative to customize your code blocks, overriding GitLab's default choice of language. - [Badges](badges.md): badges for the project overview. - [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of the source, build output, and other metadata or artifacts associated with a released version of your code. +- [Maven packages](packages/maven_repository.md): your private Maven repository in GitLab. **[PREMIUM]** +- [NPM packages](packages/npm_registry.md): your private NPM package registry in GitLab. **[PREMIUM]** +- [Code owners](code_owners.md): specify code owners for certain files **[STARTER]** +- [License Management](merge_requests/license_management.md): approve and blacklist licenses for projects. **[ULTIMATE]** ### Project integrations @@ -116,6 +130,13 @@ Read through the documentation on [project settings](settings/index.md). - [Export a project from GitLab](settings/import_export.md#exporting-a-project-and-its-data) - [Importing and exporting projects between GitLab instances](settings/import_export.md) +## CI/CD for external repositories + +Instead of importing a repository directly to GitLab, you can connect your repository +as a CI/CD project. + +Read through the documentation on [CI/CD for external repositories](../../ci/ci_cd_for_external_repos/index.md). + ## Project members Learn how to [add members to your projects](members/index.md). diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md new file mode 100644 index 00000000000..cdb0e34fdf6 --- /dev/null +++ b/doc/user/project/integrations/github.md @@ -0,0 +1,48 @@ +# GitHub project integration **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3836) in GitLab Premium 10.6. + +GitLab provides an integration for updating the pipeline statuses on GitHub. +This is especially useful if using GitLab for CI/CD only. + +This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirroring-and-pipeline-status-sharing) +and is automatically configured on [GitHub import](../../../integration/github.md). + + + +## Configuration + +### Complete these steps on GitHub + +This integration requires a [GitHub API token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) +with `repo:status` access granted: + +1. Go to your "Personal access tokens" page at https://github.com/settings/tokens +1. Click "Generate New Token" +1. Ensure that `repo:status` is checked and click "Generate token" +1. Copy the generated token to use on GitLab + +### Complete these steps on GitLab + +1. Navigate to the project you want to configure. +1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) +1. Click "GitHub". +1. Select the "Active" checkbox. +1. Paste the token you've generated on GitHub +1. Enter the path to your project on GitHub, such as `https://github.com/username/repository` +1. Optionally check "Static status check names" checkbox to enable static status check names. +1. Save or optionally click "Test Settings". + +#### Static / dynamic status check names + +Since GitLab 11.5 it is possible to opt-in to using static status check names. + +This makes it possible to mark these status checks as _Required_ on GitHub. +If you check "Static status check names" checkbox on the integration page, your +GitLab instance host name is going to be appended to a status check name, +whereas in case of dynamic status check names, a branch name is going to be +appended. + +Dynamic status check name is a default behavior. + + diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md new file mode 100644 index 00000000000..3dcd018f305 --- /dev/null +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -0,0 +1,65 @@ +# GitLab Slack application + +NOTE: **Note:** +The GitLab Slack application is only configurable for GitLab.com. It will **not** +work for on-premises installations where you can configure the +[Slack slash commands](slack_slash_commands.md) service instead. We're working +with Slack on making this configurable for all GitLab installations, but there's +no ETA. +It was first introduced in GitLab 9.4 and distributed to Slack App Directory in +GitLab 10.2. + +Slack provides a native application which you can enable via your project's +integrations on GitLab.com. + +## Slack App Directory + +The simplest way to enable the GitLab Slack application for your workspace is to +install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) from +the [Slack App Directory](https://slack.com/apps). + +Clicking install will take you to the +[GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) +where you can select a project to enable the GitLab Slack application for. + + + +## Configuration + +Alternatively, you can configure the Slack application with a project's +integration settings. + +Keep in mind that you need to have the appropriate permissions for your Slack +team in order to be able to install a new application, read more in Slack's +docs on [Adding an app to your team][slack-docs]. + +To enable GitLab's service for your Slack team: + +1. Go to your project's **Settings > Integration > Slack application** (only + visible on GitLab.com) +1. Click the "Add to Slack" button + +That's all! You can now start using the Slack slash commands. + +## Usage + +After confirming the installation, you, and everyone else in your Slack team, +can use all the [slash commands]. + +When you perform your first slash command you will be asked to authorize your +Slack user on GitLab.com. + +The only difference with the [manually configurable Slack slash commands][slack-manual] +is that all the commands should be prefixed with the `/gitlab` keyword. +We are working on making this configurable in the future. + +For example, to show the issue number `1001` under the `gitlab-org/gitlab-ce` +project, you would do: + +``` +/gitlab gitlab-org/gitlab-ce issue show 1001 +``` + +[slack-docs]: https://get.slack.help/hc/en-us/articles/202035138-Adding-apps-to-your-team +[slash commands]: ../../../integration/slash_commands.md +[slack-manual]: slack_slash_commands.md diff --git a/doc/user/project/integrations/img/github_configuration.png b/doc/user/project/integrations/img/github_configuration.png Binary files differnew file mode 100644 index 00000000000..9f2d47921c7 --- /dev/null +++ b/doc/user/project/integrations/img/github_configuration.png diff --git a/doc/user/project/integrations/img/github_status_check_pipeline_update.png b/doc/user/project/integrations/img/github_status_check_pipeline_update.png Binary files differnew file mode 100644 index 00000000000..9d02ca18497 --- /dev/null +++ b/doc/user/project/integrations/img/github_status_check_pipeline_update.png diff --git a/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png b/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png Binary files differnew file mode 100644 index 00000000000..57cd35c9f5d --- /dev/null +++ b/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png diff --git a/doc/user/project/integrations/img/jira_api_token_menu.png b/doc/user/project/integrations/img/jira_api_token_menu.png Binary files differindex 55c8fb1bdb9..14037bd0b47 100644 --- a/doc/user/project/integrations/img/jira_api_token_menu.png +++ b/doc/user/project/integrations/img/jira_api_token_menu.png diff --git a/doc/user/project/integrations/img/jira_service_page.png b/doc/user/project/integrations/img/jira_service_page.png Binary files differindex 3a27b4df841..377b69d9d06 100644 --- a/doc/user/project/integrations/img/jira_service_page.png +++ b/doc/user/project/integrations/img/jira_service_page.png diff --git a/doc/user/project/integrations/img/prometheus_add_metric.png b/doc/user/project/integrations/img/prometheus_add_metric.png Binary files differnew file mode 100644 index 00000000000..e85670e1a13 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_add_metric.png diff --git a/doc/user/project/integrations/img/prometheus_alert.png b/doc/user/project/integrations/img/prometheus_alert.png Binary files differnew file mode 100644 index 00000000000..a37f0477fd9 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_alert.png diff --git a/doc/user/project/integrations/img/prometheus_service_alerts.png b/doc/user/project/integrations/img/prometheus_service_alerts.png Binary files differnew file mode 100644 index 00000000000..a81dfe7da14 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_service_alerts.png diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index e2f23827360..6e4b1ea6b11 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -35,9 +35,11 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | | Flowdock | Flowdock is a collaboration web app for technical teams | +| [GitHub](github.md) | Sends pipeline notifications to GitHub | | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | | [JIRA](jira.md) | JIRA issue tracker | +| [Jenkins](../../../integration/jenkins.md) | An extendable open source continuous integration server | | JetBrains TeamCity CI | A continuous integration and build server | | [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | | [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | @@ -46,6 +48,7 @@ Click on the service links to see further configuration instructions and details | Pipelines emails | Email the pipeline status to a list of recipients | | [Slack Notifications](slack.md) | Send GitLab events (e.g. issue created) to Slack as notifications | | [Slack slash commands](slack_slash_commands.md) | Use slash commands in Slack to control GitLab | +| [GitLab Slack application](gitlab_slack_application.md) | Use Slack's official application | PivotalTracker | Project Management Software (Source Commits Endpoint) | | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 43a9e24526d..57d4668adaf 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -13,7 +13,7 @@ There are two ways to set up Prometheus integration, depending on where your app - For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes). - For other deployment targets, simply [specify the Prometheus server](#manual-configuration-of-prometheus). -Once enabled, GitLab will automatically detect metrics from known services in the [metric library](#monitoring-cicd-environments). +Once enabled, GitLab will automatically detect metrics from known services in the [metric library](#monitoring-cicd-environments). You are also able to [add your own metrics](#adding-additional-metrics-premium) as well. ## Enabling Prometheus Integration @@ -93,6 +93,70 @@ GitLab will automatically scan the Prometheus server for metrics from known serv You can view the performance dashboard for an environment by [clicking on the monitoring button](../../../ci/environments.md#monitoring-environments). +### Adding additional metrics **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3799) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. + +Additional metrics can be monitored by adding them on the Prometheus integration page. Once saved, they will be displayed on the environment performance dashboard. + + + +A few fields are required: + +- **Name**: Chart title +- **Type**: Type of metric. Metrics of the same type will be shown together. +- **Query**: Valid [PromQL query](https://prometheus.io/docs/prometheus/latest/querying/basics/). Note, no validation is performed at this time. If the query is not valid, the dashboard will display an error. +- **Y-axis label**: Y axis title to display on the dashboard. +- **Unit label**: Query units, for example `req / sec`. Shown next to the value. + +#### Query Variables + +GitLab supports a limited set of [CI variables](../../../ci/variables/README.html) in the Prometheus query. This is particularly useful for identifying a specific environment, for example with `CI_ENVIRONMENT_SLUG`. The supported variables are: + +- CI_ENVIRONMENT_SLUG +- KUBE_NAMESPACE + +To specify a variable in a query, enclose it in curly braces with a leading percent. For example: `%{ci_environment_slug}`. + +### Setting up alerts for Prometheus metrics **[ULTIMATE]** + +#### Managed Prometheus instances + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6590) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2 for [custom metrics](#adding-additional-metrics-premium), and 11.3 for [library metrics](prometheus_library/metrics.md). + +For managed Prometheus instances using auto configuration, alerts for metrics [can be configured](#adding-additional-metrics-premium) directly in the performance dashboard. + +To set an alert, click on the alarm icon in the top right corner of the metric you want to create the alert for. A dropdown +will appear, with options to set the threshold and operator. Click **Add** to save and activate the alert. + + + +If the metric exceeds the threshold of the alert for over 5 minutes, an email +will be sent to all [Maintainers and Owners](../../permissions.md#project-members-permissions) of the project. + +To remove the alert, click back on the alert icon for the desired metric, and click **Delete**. + +#### External Prometheus instances + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.8. + +For manually configured Prometheus servers, a notify endpoint is provided to use with Prometheus webhooks. If you have manual configuration enabled, an **Alerts** section is added to **Settings > Integrations > Prometheus**. This contains the *URL* and *Authorization Key*. The **Reset Key** button will invalidate the key and generate a new one. + + + +To send GitLab alert notifications, copy the *URL* and *Authorization Key* into the [`webhook_configs`](https://prometheus.io/docs/alerting/configuration/#webhook_config) section of your Prometheus Alertmanager configuration: + +```yaml +receivers: + name: gitlab + webhook_configs: + - http_config: + bearer_token: 9e1cbfcd546896a9ea8be557caf13a76 + send_resolved: true + url: http://192.168.178.31:3001/root/manual_prometheus/prometheus/alerts/notify.json + ... +``` + ## Determining the performance impact of a merge > [Introduced][ce-10408] in GitLab 9.2. diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 7a45c87ada0..4d523967d2a 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,6 +1,6 @@ # Monitoring Kubernetes -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935) in GitLab 9.0 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935) in GitLab 9.0. GitLab has support for automatically detecting and monitoring Kubernetes metrics. @@ -35,3 +35,25 @@ Prometheus needs to be deployed into the cluster and configured properly in orde In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. + +## Displaying Canary metrics + +> Introduced in [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15201). + +GitLab also gathers Kubernetes metrics for [canary deployments](../../canary_deployments.md), allowing easy comparison between the current deployed version and the canary. + +These metrics expect the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name to begin with `$CI_ENVIRONMENT_SLUG-canary`, to isolate the canary metrics. + +### Canary metrics supported + +- Average Memory Usage (MB) + + ``` + avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024 + ``` + +- Average CPU Utilization (%) + + ``` + avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name)) + ``` diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index 40040e44d64..1153ed1474f 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -65,6 +65,26 @@ In GitLab 11.7, we updated the format of the generated email address. However the older format is still supported, allowing existing aliases or contacts to continue working._ +## New issue via Service Desk **[PREMIUM]** + +Enable [Service Desk](../service_desk.md) to your project and offer email support. +By doing so, when your customer sends a new email, a new issue can be created in +the appropriate project and followed up from there. + +## New issue from the group-level Issue Tracker + +Head to the Group dashboard and click "Issues" in the sidebar to visit the Issue Tracker +for all projects in your Group. Select the project you'd like to add an issue for +using the dropdown button at the top-right of the page. + + + +We'll keep track of the project you selected most recently, and use it as the default +for your next visit. This should save you a lot of time and clicks, if you mostly +create issues for the same project. + + + ## New issue via URL with prefilled fields You can link directly to the new issue page for a given project, with prefilled diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md new file mode 100644 index 00000000000..56b94585672 --- /dev/null +++ b/doc/user/project/issues/csv_export.md @@ -0,0 +1,77 @@ +# Export Issues to CSV **[STARTER]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1126) in [GitLab Starter 9.0](https://about.gitlab.com/2017/03/22/gitlab-9-0-released/#export-issues-ees-eep). + +Issues can be exported as CSV from GitLab and are sent to your default notification email as an attachment. + +## Overview + +**Export Issues to CSV** enables you and your team to export all the data collected from issues into +a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) file, +which stores tabular data in plain text. + +> _CSVs are a handy way of getting data from one program to another where one program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) + +CSV files can be used with any plotter or spreadsheet-based program, such as Microsoft Excel, +Open Office Calc, or Google Spreadsheets. + +## Use cases + +Among numerous use cases for exporting issues for CSV, we can name a few: + +- Make a snapshot of issues for offline analysis or to communicate with other teams who may not be in GitLab +- Create diagrams, graphs, and charts from the CSV data +- Present the data in any other format for auditing or sharing reasons +- Import the issues elsewhere to a system outside of GitLab +- Long-term issues' data analysis with multiple snapshots created along the time +- Use the long-term data to gather relevant feedback given in the issues, and improve your product based on real metrics + +## Choosing which issues to include + +From the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned will be exported, including those not shown on the first page. + + + +You will be asked to confirm the number of issues and email address for the export, after which the email will begin being prepared. + + + +## Sorting + +Exported issues are always sorted by `Issue ID`. + +## Format + +> **Time Estimate** and **Time Spent** columns were [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2627) in GitLab Starter 10.0. +> +> **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5300) in GitLab Starter 10.8. + +Data will be encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row will be the headers, which are listed in the following table along with a description of the values: + + +| Column | Description | +|---------|-------------| +| Issue ID | Issue `iid` | +| URL | A link to the issue on GitLab | +| Title | Issue `title` | +| State | `Open` or `Closed` | +| Description | Issue `description` | +| Author | Full name of the issue author | +| Author Username | Username of the author, with the `@` symbol omitted | +| Assignee | Full name of the issue assignee | +| Assignee Username | Username of the author, with the `@` symbol omitted | +| Confidential | `Yes` or `No` | +| Locked | `Yes` or `No` | +| Due Date | Formated as `YYYY-MM-DD` | +| Created At (UTC) | Formated as `YYYY-MM-DD HH:MM:SS` | +| Updated At (UTC) | Formated as `YYYY-MM-DD HH:MM:SS` | +| Milestone | Title of the issue milestone | +| Weight | Issue weight | +| Labels | Title of any labels joined with a `,` | +| Time Estimate | [Time estimate](../../../workflow/time_tracking.md#estimates) in seconds | +| Time Spent | [Time spent](../../../workflow/time_tracking.md#time-spent) in seconds | + + +## Limitations + +As the issues will be sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 20MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. diff --git a/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png b/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png Binary files differnew file mode 100644 index 00000000000..8996490ae63 --- /dev/null +++ b/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png diff --git a/doc/user/project/issues/img/csv_export_button.png b/doc/user/project/issues/img/csv_export_button.png Binary files differnew file mode 100644 index 00000000000..f9fcfd71c2f --- /dev/null +++ b/doc/user/project/issues/img/csv_export_button.png diff --git a/doc/user/project/issues/img/csv_export_modal.png b/doc/user/project/issues/img/csv_export_modal.png Binary files differnew file mode 100644 index 00000000000..f988deec966 --- /dev/null +++ b/doc/user/project/issues/img/csv_export_modal.png diff --git a/doc/user/project/issues/img/multiple_assignees.gif b/doc/user/project/issues/img/multiple_assignees.gif Binary files differnew file mode 100644 index 00000000000..055a0efd9ae --- /dev/null +++ b/doc/user/project/issues/img/multiple_assignees.gif diff --git a/doc/user/project/issues/img/multiple_assignees_for_issues.png b/doc/user/project/issues/img/multiple_assignees_for_issues.png Binary files differnew file mode 100644 index 00000000000..e8ae37d427d --- /dev/null +++ b/doc/user/project/issues/img/multiple_assignees_for_issues.png diff --git a/doc/user/project/issues/img/related_issues_add.png b/doc/user/project/issues/img/related_issues_add.png Binary files differnew file mode 100644 index 00000000000..f59d2335386 --- /dev/null +++ b/doc/user/project/issues/img/related_issues_add.png diff --git a/doc/user/project/issues/img/related_issues_remove.png b/doc/user/project/issues/img/related_issues_remove.png Binary files differnew file mode 100644 index 00000000000..be2ec59e61b --- /dev/null +++ b/doc/user/project/issues/img/related_issues_remove.png diff --git a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png Binary files differnew file mode 100644 index 00000000000..97d93620b2a --- /dev/null +++ b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png diff --git a/doc/user/project/issues/img/similar_issues.png b/doc/user/project/issues/img/similar_issues.png Binary files differindex 0dfb5b00e02..c5b7902b2ac 100644 --- a/doc/user/project/issues/img/similar_issues.png +++ b/doc/user/project/issues/img/similar_issues.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 907a305fe23..94235eb1fdd 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -34,7 +34,7 @@ your project public, open to collaboration. ### Streamline collaboration -With [Multiple Assignees for Issues](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html), +With [Multiple Assignees for Issues](multiple_assignees_for_issues.md), available in [GitLab Starter](https://about.gitlab.com/pricing/) you can streamline collaboration and allow shared responsibilities to be clearly displayed. All assignees are shown across your workflows and receive notifications (as they @@ -139,8 +139,19 @@ Find GitLab Issue Boards by navigating to your **Project's Dashboard** > **Issue Read through the documentation for [Issue Boards](../issue_board.md) to find out more about this feature. -With [GitLab Starter](https://about.gitlab.com/pricing/), you can also -create various boards per project with [Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board.html#multiple-issue-boards). +### Export Issues to CSV **[STARTER]** + +Issues can be [exported as CSV](csv_export.md) from GitLab and are sent to your email as an attachment. + +_Exporting issues to CSV is available only in [GitLab Enterprise Edition](https://about.gitlab.com/products/)._ + +### Related Issues **[STARTER]** + +Related Issues are a bi-directional relationship between any two issues +and appear in a block below the issue description. Issues can be across groups +and projects. + +Read more about [Related Issues](related_issues.md). ### Import Issues from CSV diff --git a/doc/user/project/issues/issues_functionalities.md b/doc/user/project/issues/issues_functionalities.md index 27b9dc51760..ebbccd4162b 100644 --- a/doc/user/project/issues/issues_functionalities.md +++ b/doc/user/project/issues/issues_functionalities.md @@ -50,7 +50,7 @@ where there is shared ownership of an issue. In [GitLab Starter](https://about.gitlab.com/pricing/), you can assign multiple people to an issue. -Learn more in the [Multiple Assignees documentation](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html). +Learn more in the [Multiple Assignees documentation](multiple_assignees_for_issues.md). #### 4. Milestone @@ -90,7 +90,7 @@ If a label doesn't exist yet, you can click **Edit**, and it opens a dropdown me - Assign a weight. Larger values are used to indicate more effort is required to complete the issue. Only positive values or zero are allowed. -Learn more in the [Issue Weight documentation](https://docs.gitlab.com/ee/workflow/issue_weight.html). +Learn more in the [Issue Weight documentation](../../../workflow/issue_weight.md). #### 9. Participants diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md new file mode 100644 index 00000000000..8781ebdd5b0 --- /dev/null +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -0,0 +1,41 @@ +# Multiple Assignees for Issues **[STARTER]** + +> **Note:** +[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1904) +in [GitLab Starter 9.2](https://about.gitlab.com/2017/05/22/gitlab-9-2-released/#multiple-assignees-for-issues). + +## Overview + +In large teams, where there is shared ownership of an issue, it can be difficult +to track who is working on it, who already completed their contributions, who +didn't even start yet. + +In [GitLab Enterprise Edition](https://about.gitlab.com/pricing/), +you can also select multiple assignees to an issue, making it easier to +track, and making clearer who is accountable for it. + + + +## Use cases + +Consider a team formed by frontend developers, backend developers, +UX designers, QA testers, and a product manager working together to bring an idea to +market. + +Multiple Assignees for Issues makes collaboration smother, +and allows shared responsibilities to be clearly displayed. +All assignees are shown across your team's workflows and receive notifications (as they +would as single assignees), simplifying communication and ownership. + +Once an assignee had their work completed, they would remove themselves as assignees, making +it clear that their role is complete. + +## How it works + +From an opened issue, expand the right sidebar, locate the assignees entry, +and click on **Edit**. From the dropdown menu, select as many users as you want +to assign the issue to. + + + +An assignee can be easily removed by deselecting them from the same dropdown menu. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md new file mode 100644 index 00000000000..7180bd1d297 --- /dev/null +++ b/doc/user/project/issues/related_issues.md @@ -0,0 +1,37 @@ +# Related issues **[STARTER]** + +> [Introduced][ee-1797] in [GitLab Starter][ee] 9.4. + +Related issues are a bi-directional relationship between any two issues +and appear in a block below the issue description. Issues can be across groups +and projects. + +The relationship only shows up in the UI if the user can see both issues. + +## Adding a related issue + +You can relate one issue to another by clicking the related issues "+" button +in the header of the related issue block. Then input the issue reference number +or paste in a link to the issue. + +Valid references will be added to a temporary list that you can review. +When ready, click the green "Add related issues" button to submit. + + + +## Removing a related issue + +In the related issues block, click the "x" icon on the right-side of each issue +token that you wish to remove. Due to the bi-directional relationship, it +will no longer appear in either issue. + + + +Please access our [permissions] page for more information. + +Additionally, you are also able to manage related issues through [our API]. + +[ee]: https://about.gitlab.com/pricing/ +[ee-1797]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1797 +[permissions]: ../../permissions.md +[Our API]: ../../../api/issue_links.md diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 9c045dfcce4..fa073e659aa 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -8,7 +8,7 @@ Labels allow you to categorize issues or merge requests using descriptive titles In GitLab, you can create project and group labels: -- **Project labels** can be assigned to issues or merge requests in that project only. +- **Project labels** can be assigned to issues or merge requests in that project only. - **Group labels** can be assigned to any issue or merge request of any project in that group or any subgroups of the group. ## Creating labels @@ -35,6 +35,9 @@ GitLab will add the following default labels to the project: To create a **group label**, follow similar steps from above to project labels. Navigate to **Issues > Labels** in the group and create it from there. This page only shows group labels in this group. +Alternatively, you can create group labels also from Epic sidebar. Please note that the created label will belong to the immediate group to which epic belongs. + + Group labels appear in every label list page of the group's child projects. @@ -81,7 +84,7 @@ top-right: GitLab will consider the label title and description for the search. -## Filtering issues and merge requests by label +## Filtering issues, merge requests and epics by label ### Filtering in list pages @@ -89,11 +92,16 @@ From the project issue list page and the project merge request list page, you ca From the group issue list page and the group merge request list page, you can [filter](../search/index.md#issues-and-merge-requests) by both group labels (including subgroup ancestors and subgroup descendants) and project labels. +From the group epic list page, you can [filter](../search/index.md#issues-and-merge-requests) by both current group labels as well as decendent group labels. +  ### Filtering in issue boards - From [project boards](issue_board.md), you can filter by both group labels and project labels in the [search and filter bar](../search/index.md#issue-boards). +- From [group issue boards](issue_board.md#group-issue-boards), you can filter by only group labels in the [search and filter bar](../search/index.md#issue-boards). **[PREMIUM]** +- From [project boards](issue_board.md), you can filter by both group labels and project labels in the [issue board configuration](issue_board.md#board-with-configuration). **[PREMIUM]** +- From [group issue boards](issue_board.md#group-issue-boards), you can filter by only group labels in the [issue board configuration](issue_board.md#board-with-configuration). **[PREMIUM]** ## Subscribing to labels diff --git a/doc/user/project/maven_packages.md b/doc/user/project/maven_packages.md new file mode 100644 index 00000000000..48835a2dac7 --- /dev/null +++ b/doc/user/project/maven_packages.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'packages/maven_repository.md' +--- + +This document was moved to [another location](packages/maven_repository.md). diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md new file mode 100644 index 00000000000..65ee2e128ae --- /dev/null +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -0,0 +1,54 @@ +# Browser Performance Testing **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3507) +in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3. + +## Overview + +If your application offers a web interface and you are using +[GitLab CI/CD](../../../ci/README.md), you can quickly determine the performance +impact of pending code changes. + +GitLab uses [Sitespeed.io](https://www.sitespeed.io), a free and open source +tool for measuring the performance of web sites, and has built a simple +[Sitespeed plugin](https://gitlab.com/gitlab-org/gl-performance) +which outputs the results in a file called `performance.json`. This plugin +outputs the performance score for each page that is analyzed. + +The [Sitespeed.io performance score](http://examples.sitespeed.io/6.0/2017-11-23-23-43-35/help.html) +is a composite value based on best practices, and we will be expanding support +for [additional metrics](https://gitlab.com/gitlab-org/gitlab-ee/issues/4370) +in a future release. + +Going a step further, GitLab can show the Performance report right +in the merge request widget area: + +## Use cases + +For instance, consider the following workflow: + +1. A member of the marketing team is attempting to track engagement by adding a new tool +1. With browser performance metrics, they see how their changes are impacting the usability of the page for end users +1. The metrics show that after their changes the performance score of the page has gone down +1. When looking at the detailed report, they see that the new Javascript library was included in `<head>` which affects loading page speed +1. They ask a front end developer to help them, who sets the library to load asynchronously +1. The frontend developer approves the merge request and authorizes its deployment to production + +## How it works + +First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the +[Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance-premium). +For more information on how the Performance job should look like, check the +example on [Testing Browser Performance](../../../ci/examples/browser_performance.md). + +GitLab then checks this report, compares key performance metrics for each page +between the source and target branches, and shows the information right on the merge request. + +>**Note:** +If the Performance report doesn't have anything to compare to, no information +will be displayed in the merge request area. That is the case when you add the +Performance job in your `.gitlab-ci.yml` for the very first time. +Consecutive merge requests will have something to compare to and the Performance +report will be shown properly. + + diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md new file mode 100644 index 00000000000..e6811b5df5e --- /dev/null +++ b/doc/user/project/merge_requests/code_quality.md @@ -0,0 +1,82 @@ +# Code Quality **[STARTER]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1984) +in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your +source code quality using GitLab Code Quality. +Code Quality uses [Code Climate Engines](https://codeclimate.com), which are +free and open source. Code Quality doesn’t require a Code Climate subscription. + +Going a step further, GitLab can show the Code Quality report right +in the merge request widget area: + + + +## Use cases + +For instance, consider the following workflow: + +1. Your backend team member starts a new implementation for making certain feature in your app faster +1. With Code Quality reports, they analyze how their implementation is impacting the code quality +1. The metrics show that their code degrade the quality in 10 points +1. You ask a co-worker to help them with this modification +1. They both work on the changes until Code Quality report displays no degradations, only improvements +1. You approve the merge request and authorize its deployment to staging +1. Once verified, their changes are deployed to production + +## How it works + +First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the +[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality-starter). + +The Code Quality report artifact is a subset of the +[Code Climate spec](https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types). +It must be a JSON file containing an array of objects with the following properties: + +| Name | Description | +| ---------------------- | -------------------------------------------------------------------------------------- | +| `description` | A description of the code quality violation. | +| `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | +| `location.path` | The relative path to the file containing the code quality violation. | +| `location.lines.begin` | The line on which the code quality violation occurred. | + +Example: + +```json +[ + { + "description": "'unused' is assigned a value but never used.", + "fingerprint": "7815696ecbf1c96e6894b779456d330e", + "location": { + "path": "lib/index.js", + "lines": { + "begin": 42 + } + } + } +] +``` + +NOTE: **Note:** +Although the Code Climate spec supports more properties, those are ignored by GitLab. + +For more information on how the Code Quality job should look like, check the +example on [analyzing a project's code quality](../../../ci/examples/code_quality.md). + +GitLab then checks this report, compares the metrics between the source and target +branches, and shows the information right on the merge request. + +CAUTION: **Caution:** +If multiple jobs in a pipeline generate a code quality artifact, only the artifact from +the last created job (the job with the largest job ID) is used. To avoid confusion, +configure only one job to generate a code quality artifact. + +NOTE: **Note:** +If the Code Quality report doesn't have anything to compare to, no information +will be displayed in the merge request area. That is the case when you add the +Code Quality job in your `.gitlab-ci.yml` for the very first time. +Consecutive merge requests will have something to compare to and the Code Quality +report will be shown properly. diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md new file mode 100644 index 00000000000..890058eec6f --- /dev/null +++ b/doc/user/project/merge_requests/code_quality_diff.md @@ -0,0 +1,6 @@ +--- +redirect_from: 'https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html' +redirect_to: 'code_quality.md' +--- + +This document was moved to [another location](code_quality.md). diff --git a/doc/user/project/merge_requests/container_scanning.md b/doc/user/project/merge_requests/container_scanning.md new file mode 100644 index 00000000000..5d94e3eef16 --- /dev/null +++ b/doc/user/project/merge_requests/container_scanning.md @@ -0,0 +1,42 @@ +# Container Scanning **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. + +> [Introduced][ee-3672] in [GitLab Ultimate][ee] 10.4. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your Docker images for known +vulnerabilities using [Clair](https://github.com/coreos/clair), +a Vulnerability Static Analysis tool for containers. + +You can take advantage of Container Scanning by either [including the CI job](../../../ci/examples/container_scanning.md) in +your existing `.gitlab-ci.yml` file or by implicitly using +[Auto Container Scanning](../../../topics/autodevops/index.md#auto-container-scanning) +that is provided by [Auto DevOps](../../../topics/autodevops/index.md). + +Going a step further, GitLab can show the vulnerability list right in the merge +request widget area. + + + +## Use cases + +If you distribute your application with Docker, then there's a great chance +that your image is based on other Docker images that may in turn contain some +known vulnerabilities that could be exploited. + +Having an extra job in your pipeline that checks for those vulnerabilities, +and the fact that they are displayed inside a merge request, makes it very easy +to perform audits for your Docker-based apps. + +## How it works + +First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the +[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate). +For more information on how the Container Scanning job should look like, check the +example on [Container Scanning with GitLab CI/CD](../../../ci/examples/container_scanning.md). + +GitLab then checks this report, compares the found vulnerabilities between the source and target +branches, and shows the information right on the merge request. diff --git a/doc/user/project/merge_requests/dast.md b/doc/user/project/merge_requests/dast.md new file mode 100644 index 00000000000..9560f373a70 --- /dev/null +++ b/doc/user/project/merge_requests/dast.md @@ -0,0 +1,45 @@ +# Dynamic Application Security Testing (DAST) **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4348) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. + +## Overview + +Running [static checks](sast.md) on your code is the first step to detect +vulnerabilities that can put the security of your code at risk. Yet, once +deployed, your application is exposed to a new category of possible attacks, +such as cross-site scripting or broken authentication flaws. This is where +Dynamic Application Security Testing (DAST) comes into place. + +If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web application(s) +for known vulnerabilities using Dynamic Application Security Testing (DAST). + +You can take advantage of DAST by either [including the CI job](../../../ci/examples/dast.md) in +your existing `.gitlab-ci.yml` file or by implicitly using +[Auto DAST](../../../topics/autodevops/index.md#auto-dast-ultimate) +that is provided by [Auto DevOps](../../../topics/autodevops/index.md). + +Going a step further, GitLab can show the vulnerability list right in the merge +request widget area. + +## Use cases + +It helps you automatically find security vulnerabilities in your running web +applications while you are developing and testing your applications. + +## How it works + +First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the +[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate). +For more information on how the DAST job should look like, check the +example on [Dynamic Application Security Testing with GitLab CI/CD](../../../ci/examples/dast.md). + +GitLab then checks this report, compares the found vulnerabilities between the source and target +branches, and shows the information right on the merge request. + + + +By clicking on one of the detected linked vulnerabilities, you will be able to +see the details and the URL(s) affected. + + diff --git a/doc/user/project/merge_requests/dependency_scanning.md b/doc/user/project/merge_requests/dependency_scanning.md new file mode 100644 index 00000000000..09916b75863 --- /dev/null +++ b/doc/user/project/merge_requests/dependency_scanning.md @@ -0,0 +1,50 @@ +# Dependency Scanning **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your dependencies for known +vulnerabilities using Dependency Scanning. + +You can take advantage of Dependency Scanning by either [including the CI job](../../../ci/examples/dependency_scanning.md) in +your existing `.gitlab-ci.yml` file or by implicitly using +[Auto Dependency Scanning](../../../topics/autodevops/index.md#auto-dependency-scanning-ultimate) +that is provided by [Auto DevOps](../../../topics/autodevops/index.md). + +Going a step further, GitLab can show the vulnerability list right in the merge +request widget area. + +## Use cases + +It helps you automatically find security vulnerabilities in your dependencies +while you are developing and testing your applications. E.g. your application +is using an external (open source) library which is known to be vulnerable. + +## Supported languages and dependency managers + +The following languages and dependency managers are supported. + +| Language (package managers) | Scan tool | +|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), [Retire.js](https://retirejs.github.io/retire.js) | +| Python ([pip](https://pip.pypa.io/en/stable/)) (only `requirements.txt` supported) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | +| Ruby ([gem](https://rubygems.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), [bundler-audit](https://github.com/rubysec/bundler-audit) | +| Java ([Maven](https://maven.apache.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | +| PHP ([Composer](https://getcomposer.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | + +Some scanners require to send a list of project dependencies to GitLab central servers to check for vulnerabilities. To learn more about this or to disable it please +check [GitLab Dependency Scanning documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks). + +## How it works + +First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the +[Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate). +For more information on how the Dependency Scanning job should look like, check the +example on [Dependency Scanning with GitLab CI/CD](../../../ci/examples/dependency_scanning.md). + +GitLab then checks this report, compares the found vulnerabilities between the source and target +branches, and shows the information right on the merge request. + + diff --git a/doc/user/project/merge_requests/img/approvals_can_override.png b/doc/user/project/merge_requests/img/approvals_can_override.png Binary files differnew file mode 100644 index 00000000000..8d207d018e0 --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_can_override.png diff --git a/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png b/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png Binary files differnew file mode 100644 index 00000000000..b6dc86f312e --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_premium_mr_widget.png diff --git a/doc/user/project/merge_requests/img/approvals_premium_project_edit.png b/doc/user/project/merge_requests/img/approvals_premium_project_edit.png Binary files differnew file mode 100644 index 00000000000..b6f6188b9cd --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_premium_project_edit.png diff --git a/doc/user/project/merge_requests/img/approvals_remove_on_push.png b/doc/user/project/merge_requests/img/approvals_remove_on_push.png Binary files differnew file mode 100644 index 00000000000..73964827587 --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_remove_on_push.png diff --git a/doc/user/project/merge_requests/img/approvals_starter_project_edit.png b/doc/user/project/merge_requests/img/approvals_starter_project_edit.png Binary files differnew file mode 100644 index 00000000000..868b9d58740 --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_starter_project_edit.png diff --git a/doc/user/project/merge_requests/img/approvals_starter_project_empty.png b/doc/user/project/merge_requests/img/approvals_starter_project_empty.png Binary files differnew file mode 100644 index 00000000000..7375820224c --- /dev/null +++ b/doc/user/project/merge_requests/img/approvals_starter_project_empty.png diff --git a/doc/user/project/merge_requests/img/approve.png b/doc/user/project/merge_requests/img/approve.png Binary files differnew file mode 100644 index 00000000000..e68259ac5c2 --- /dev/null +++ b/doc/user/project/merge_requests/img/approve.png diff --git a/doc/user/project/merge_requests/img/approve_additionally.png b/doc/user/project/merge_requests/img/approve_additionally.png Binary files differnew file mode 100644 index 00000000000..3db5a9159e5 --- /dev/null +++ b/doc/user/project/merge_requests/img/approve_additionally.png diff --git a/doc/user/project/merge_requests/img/browser_performance_testing.png b/doc/user/project/merge_requests/img/browser_performance_testing.png Binary files differnew file mode 100644 index 00000000000..eea77fb8b93 --- /dev/null +++ b/doc/user/project/merge_requests/img/browser_performance_testing.png diff --git a/doc/user/project/merge_requests/img/code_quality.gif b/doc/user/project/merge_requests/img/code_quality.gif Binary files differnew file mode 100644 index 00000000000..bab921cf38b --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality.gif diff --git a/doc/user/project/merge_requests/img/comment-on-any-diff-line.png b/doc/user/project/merge_requests/img/comment-on-any-diff-line.png Binary files differindex c2455c2d1e5..5b9844bf02f 100644 --- a/doc/user/project/merge_requests/img/comment-on-any-diff-line.png +++ b/doc/user/project/merge_requests/img/comment-on-any-diff-line.png diff --git a/doc/user/project/merge_requests/img/container_scanning.png b/doc/user/project/merge_requests/img/container_scanning.png Binary files differnew file mode 100644 index 00000000000..e47f62acd9d --- /dev/null +++ b/doc/user/project/merge_requests/img/container_scanning.png diff --git a/doc/user/project/merge_requests/img/dast_all.png b/doc/user/project/merge_requests/img/dast_all.png Binary files differnew file mode 100644 index 00000000000..b6edc928dc3 --- /dev/null +++ b/doc/user/project/merge_requests/img/dast_all.png diff --git a/doc/user/project/merge_requests/img/dast_single.png b/doc/user/project/merge_requests/img/dast_single.png Binary files differnew file mode 100644 index 00000000000..26ca4bde786 --- /dev/null +++ b/doc/user/project/merge_requests/img/dast_single.png diff --git a/doc/user/project/merge_requests/img/dependency_scanning.png b/doc/user/project/merge_requests/img/dependency_scanning.png Binary files differnew file mode 100644 index 00000000000..18df356f846 --- /dev/null +++ b/doc/user/project/merge_requests/img/dependency_scanning.png diff --git a/doc/user/project/merge_requests/img/filter_approver_merge_requests.png b/doc/user/project/merge_requests/img/filter_approver_merge_requests.png Binary files differnew file mode 100644 index 00000000000..9c386391a4f --- /dev/null +++ b/doc/user/project/merge_requests/img/filter_approver_merge_requests.png diff --git a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png Binary files differindex 81878709487..6d511efd049 100644 --- a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png +++ b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png diff --git a/doc/user/project/merge_requests/img/interactive_reports.png b/doc/user/project/merge_requests/img/interactive_reports.png Binary files differnew file mode 100644 index 00000000000..9f9812dc69d --- /dev/null +++ b/doc/user/project/merge_requests/img/interactive_reports.png diff --git a/doc/user/project/merge_requests/img/license_management.png b/doc/user/project/merge_requests/img/license_management.png Binary files differnew file mode 100644 index 00000000000..cdce6b5fe38 --- /dev/null +++ b/doc/user/project/merge_requests/img/license_management.png diff --git a/doc/user/project/merge_requests/img/license_management_decision.png b/doc/user/project/merge_requests/img/license_management_decision.png Binary files differnew file mode 100644 index 00000000000..0763130c375 --- /dev/null +++ b/doc/user/project/merge_requests/img/license_management_decision.png diff --git a/doc/user/project/merge_requests/img/license_management_pipeline_tab.png b/doc/user/project/merge_requests/img/license_management_pipeline_tab.png Binary files differnew file mode 100644 index 00000000000..80ffca815b9 --- /dev/null +++ b/doc/user/project/merge_requests/img/license_management_pipeline_tab.png diff --git a/doc/user/project/merge_requests/img/license_management_settings.png b/doc/user/project/merge_requests/img/license_management_settings.png Binary files differnew file mode 100644 index 00000000000..b5490e59074 --- /dev/null +++ b/doc/user/project/merge_requests/img/license_management_settings.png diff --git a/doc/user/project/merge_requests/img/remove_approval.png b/doc/user/project/merge_requests/img/remove_approval.png Binary files differnew file mode 100644 index 00000000000..6083e1745ef --- /dev/null +++ b/doc/user/project/merge_requests/img/remove_approval.png diff --git a/doc/user/project/merge_requests/img/sast.png b/doc/user/project/merge_requests/img/sast.png Binary files differnew file mode 100644 index 00000000000..2c75592c32a --- /dev/null +++ b/doc/user/project/merge_requests/img/sast.png diff --git a/doc/user/project/merge_requests/img/security_report.png b/doc/user/project/merge_requests/img/security_report.png Binary files differnew file mode 100644 index 00000000000..ba41b707238 --- /dev/null +++ b/doc/user/project/merge_requests/img/security_report.png diff --git a/doc/user/project/merge_requests/img/vulnerability_solution.png b/doc/user/project/merge_requests/img/vulnerability_solution.png Binary files differnew file mode 100644 index 00000000000..7443b9b6eea --- /dev/null +++ b/doc/user/project/merge_requests/img/vulnerability_solution.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 593eb80e044..11d5269e386 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -23,7 +23,7 @@ With GitLab merge requests, you can: - Assign it to any registered user, and change the assignee how many times you need - Assign a [milestone](../../project/milestones/index.md) and track the development of a broader implementation - Organize your issues and merge requests consistently throughout the project with [labels](../../project/labels.md) -- Add a time estimation and the time spent with that merge request with [Time Tracking](../../../workflow/time_tracking.html#time-tracking) +- Add a time estimation and the time spent with that merge request with [Time Tracking](../../../workflow/time_tracking.md#time-tracking) - [Resolve merge conflicts from the UI](#resolve-conflicts) - Enable [fast-forward merge requests](#fast-forward-merge-requests) - Enable [semi-linear history merge requests](#semi-linear-history-merge-requests) as another security layer to guarantee the pipeline is passing in the target branch @@ -33,9 +33,16 @@ With GitLab merge requests, you can: With **[GitLab Enterprise Edition][ee]**, you can also: -- View the deployment process across projects with [Multi-Project Pipeline Graphs](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html#multi-project-pipeline-graphs) **[PREMIUM]** -- Request [approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your managers **[STARTER]** -- Analyze the impact of your changes with [Code Quality reports](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html) **[STARTER]** +- Prepare a full review and submit it once it's ready with [Merge Request Reviews](../../discussions/index.md#merge-request-reviews-premium) **[PREMIUM]** +- View the deployment process across projects with [Multi-Project Pipelines](../../../ci/multi_project_pipelines.md) **[PREMIUM]** +- Request [approvals](merge_request_approvals.md) from your managers **[STARTER]** +- Analyze the impact of your changes with [Code Quality reports](code_quality.md) **[STARTER]** +- Manage the licenses of your dependencies with [License Management](#license-management-ultimate) **[ULTIMATE]** +- Analyze your source code for vulnerabilities with [Static Application Security Testing](sast.md) **[ULTIMATE]** +- Analyze your running web applications for vulnerabilities with [Dynamic Application Security Testing](dast.md) **[ULTIMATE]** +- Analyze your dependencies for vulnerabilities with [Dependency Scanning](dependency_scanning.md) **[ULTIMATE]** +- Analyze your Docker images for vulnerabilities with [Container Scanning](container_scanning.md) **[ULTIMATE]** +- Determine the performance impact of changes with [Browser Performance Testing](#browser-performance-testing-premium) **[PREMIUM]** ## Use cases @@ -43,19 +50,21 @@ A. Consider you are a software developer working in a team: 1. You checkout a new branch, and submit your changes through a merge request 1. You gather feedback from your team +1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) **[STARTER]** 1. You verify your changes with [JUnit test reports](../../../ci/junit_test_reports.md) in GitLab CI/CD -1. You request the approval from your manager -1. Your manager pushes a commit with his final review, [approves the merge request](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds) (Merge Request Approvals are available in GitLab Starter) +1. You avoid using dependencies whose license is not compatible with your project with [License Management reports](license_management.md) **[ULTIMATE]** +1. You request the [approval](#merge-request-approvals-starter) from your manager +1. Your manager pushes a commit with their final review, [approves the merge request](merge_request_approvals.md), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds) (Merge Request Approvals are available in GitLab Starter) 1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD 1. Your implementations were successfully shipped to your customer -B. Consider you're a web developer writing a webpage for your company's: +B. Consider you're a web developer writing a webpage for your company's website: 1. You checkout a new branch, and submit a new page through a merge request 1. You gather feedback from your reviewers 1. Your changes are previewed with [Review Apps](../../../ci/review_apps/index.md) 1. You request your web designers for their implementation -1. You request the [approval](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your manager **[STARTER]** +1. You request the [approval](merge_request_approvals.md) from your manager **[STARTER]** 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) 1. Your production team [cherry picks](#cherry-pick-changes) the merge commit into production @@ -159,6 +168,21 @@ in a Merge Request. To do so, click the **...** button in the gutter of the Merg  +## Perform a Review **[PREMIUM]** + +Start a review in order to create multiple comments on a diff and publish them once you're ready. +Starting a review allows you to get all your thoughts in order and ensure you haven't missed anything +before submitting all your comments. + +[Learn more about Merge Request Reviews](../../discussions/index.md#merge-request-reviews-premium) + +## Squash and merge + +GitLab allows you to squash all changes present in a merge request into a single +commit when merging, to allow for a neater commit history. + +[Learn more about squash and merge.](squash_and_merge.md) + ## Suggest changes > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6. @@ -256,6 +280,111 @@ have been marked as a **Work In Progress**. [Learn more about settings a merge request as "Work In Progress".](work_in_progress_merge_requests.md) +## Merge request approvals **[STARTER]** + +> Included in [GitLab Starter][products]. + +If you want to make sure every merge request is approved by one or more people, +you can enforce this workflow by using merge request approvals. Merge request +approvals allow you to set the number of necessary approvals and predefine a +list of approvers that will need to approve every merge request in a project. + +[Read more about merge request approvals.](merge_request_approvals.md) + +## Code Quality **[STARTER]** + +> Introduced in [GitLab Starter][products] 9.3. + +If you are using [GitLab CI][ci], you can analyze your source code quality using +the [Code Climate][cc] analyzer [Docker image][cd]. Going a step further, GitLab +can show the Code Climate report right in the merge request widget area. + +[Read more about Code Quality reports.](code_quality.md) + +## Browser Performance Testing **[PREMIUM]** + +> Introduced in [GitLab Premium][products] 10.3. + +If your application offers a web interface and you are using [GitLab CI/CD][ci], you can quickly determine the performance impact of pending code changes. GitLab uses [Sitespeed.io][sitespeed], a free and open source tool for measuring the performance of web sites, to analyze the performance of specific pages. + +GitLab runs the [Sitespeed.io container][sitespeed-container] and displays the difference in overall performance scores between the source and target branches. + +[Read more about Browser Performance Testing.](browser_performance_testing.md) + +## License Management **[ULTIMATE]** + +> Introduced in [GitLab Ultimate][products] 11.0. + +If you are using [GitLab CI/CD][ci], you can search your dependencies for their +licenses using License Management. +Going a step further, GitLab can show the licenses report right in the +merge request widget area. + +[Read more about License Management reports.](license_management.md) + +## Security reports **[ULTIMATE]** + +GitLab can scan and report any vulnerabilities found in your project. The +following security reports are available: + +- [Static Application Security Testing reports](sast.md) - Analyze your source + code for known vulnerabilities using Static Application Security Testing (SAST) + and see the security report right in your merge requests. +- [Dynamic Application Security Testing reports](dast.md) - Analyze your running + web application(s) for known vulnerabilities using Dynamic Application Security + Testing (DAST) and see the security report right in your merge requests. +- [Dependency Scanning reports](dependency_scanning.md) - Analyze your + dependencies for known vulnerabilities using Dependency Scanning and see the + security report right in your merge requests. +- [Container Scanning reports](container_scanning.md) - Analyze your Docker + images for known vulnerabilities and see the security report right in your + merge requests. + +### Interacting with security reports **[ULTIMATE]** + +> Introduced in [GitLab Ultimate][products] 10.8. + +CAUTION: **Warning:** +This feature is currently [Alpha](https://about.gitlab.com/handbook/product/#alpha-beta-ga) and while you can start using it, it may receive important changes in the future. + +Each security vulnerability in the report is actionable. Clicking on an entry, +a detailed information will pop up with two different possible options: + +- **Dismiss vulnerability** - Dismissing a vulnerability will place a <s>strikethrough</s> styling on it. +- **Create issue** - The new issue will have the title and description + pre-populated with the information from the vulnerability report and is created as [confidential](../issues/confidential_issues.md) by default. +- **Solution** - For some vulnerabilities ([Dependency Scanning](dependency_scanning.md) and [Container Scanning](container_scanning.md)) + a solution is provided for how to fix the vulnerability. + + + +You can also revert your dismissal or see the linked issue after the action has +been taken. + +### Solutions for Dependency Scanning **[ULTIMATE]** + +> Introduced in [GitLab Ultimate][products] 11.7. + +CAUTION: **Warning:** Automatic Patch creation is only available for a subset of [Dependency Scanning](dependency_scanning.md). At the moment only Node.JS projects managed with yarn are supported. + +Some Vulnerabilities can be fixed by applying a patch that is automatically generated by GitLab. To apply the fix: + +1. Download and review the patch file `remediation.patch`. +2. Ensure your local project has the same commit checked out that was used to generate the patch. +3. Run `git apply remediation.patch`. +4. Verify and commit the changes to your branch. + + + +## Live preview with Review Apps + +If you configured [Review Apps](https://about.gitlab.com/features/review-apps/) for your project, +you can preview the changes submitted to a feature-branch through a merge request +in a per-branch basis. No need to checkout the branch, install and preview locally; +all your changes will be available to preview by anyone with the Review Apps link. + +[Read more about Review Apps.](../../../ci/review_apps/index.md) + ## Merge request diff file navigation When reviewing changes in the **Changes** tab the diff can be navigated using @@ -448,5 +577,11 @@ And to check out a particular merge request: git checkout origin/merge-requests/1 ``` +[products]: https://about.gitlab.com/products/ "GitLab products page" [protected branches]: ../protected_branches.md +[ci]: ../../../ci/README.md +[cc]: https://codeclimate.com/ +[cd]: https://hub.docker.com/r/codeclimate/codeclimate/ +[sitespeed]: https://www.sitespeed.io +[sitespeed-container]: https://hub.docker.com/r/sitespeedio/sitespeed.io/ [ee]: https://about.gitlab.com/pricing/ "GitLab Enterprise Edition" diff --git a/doc/user/project/merge_requests/license_management.md b/doc/user/project/merge_requests/license_management.md new file mode 100644 index 00000000000..9bed3c0480a --- /dev/null +++ b/doc/user/project/merge_requests/license_management.md @@ -0,0 +1,102 @@ +# License Management **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5483) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can search your project dependencies for their licenses +using License Management. + +You can take advantage of License Management by either [including the CI job](../../../ci/examples/license_management.md) in +your existing `.gitlab-ci.yml` file or by implicitly using +[Auto License Management](../../../topics/autodevops/index.md#auto-license-management-ultimate) +that is provided by [Auto DevOps](../../../topics/autodevops/index.md). + +In addition, you can [manually approve or blacklist](#manual-license-management) licenses in the project's settings. + +Going a step further, GitLab can show the licenses list right in the merge +request widget area, highlighting the presence of licenses you don't want to use, or new +ones that need a decision. + +## Use cases + +It helps you find what licenses your project uses in its dependencies, and decide for each of then +whether to allow it or forbid it. For example, your application is using an external (open source) +library whose license is incompatible with yours. + +## Supported languages and package managers + +The following languages and package managers are supported. + +| Language | Package managers | +|------------|-------------------------------------------------------------------| +| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) | +| Go | [Godep](https://github.com/tools/godep), go get | +| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | +| .NET | [Nuget](https://www.nuget.org/) | +| Python | [pip](https://pip.pypa.io/en/stable/) | +| Ruby | [gem](https://rubygems.org/) | + +## How it works + +First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the +[License Management report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate). +For more information on how the License Management job should look like, check the +example on [Dependencies license management with GitLab CI/CD](../../../ci/examples/license_management.md). + +GitLab then checks this report, compares the licenses between the source and target +branches, and shows the information right on the merge request. +Blacklisted licenses will be clearly visible with an `x` red icon next to them +as well as new licenses which need a decision from you. + +NOTE: **Note:** +If the license management report doesn't have anything to compare to, no information +will be displayed in the merge request area. That is the case when you add the +`license_management` job in your `.gitlab-ci.yml` for the first time. +Consecutive merge requests will have something to compare to and the license +management report will be shown properly. + + + +If you are a project or group Maintainer, you can click on a license to be given +the choice to approve it or blacklist it. + + + +### Project policies for license management + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5940) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. + +From the project's settings: + +- The list of licenses and their status can be managed. +- Licenses can be manually approved or blacklisted. + +To approve or blacklist a license: + +1. Either use the **Manage licenses** button in the merge request widget, or + navigate to the project's **Settings > CI/CD** and expand the + **License Management** section. +1. Click the **Add a license** button. +1. In the **License name** dropdown, either: + - Select one of the available licenses. You can search for licenses in the field + at the top of the list. + - Enter arbitrary text in the field at the top of the list. This will cause the text to be + added as a license name to the list. +1. Select the **Approve** or **Blacklist** radio button to approve or blacklist respectively + the selected license. + +  + +## License Management report under pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5491) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2. + +From your project's left sidebar, navigate to **CI/CD > Pipelines** and click on the +pipeline ID that has a `license_management` job to see the Licenses tab with the listed +licenses (if any). + + diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md new file mode 100644 index 00000000000..b91e07b9812 --- /dev/null +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -0,0 +1,299 @@ +# Merge request approvals **[STARTER]** + +> Introduced in [GitLab Enterprise Edition 7.12](https://about.gitlab.com/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only). + +NOTE: **Note:** +If you are running a self-managed instance, the new interface shown on +this page will not be available unless the feature flag +`approval_rules` is enabled, which can be done from the Rails console by +instance administrators. + +Use these commands to start the Rails console: + +```sh +# Omnibus GitLab +gitlab-rails console + +# Installation from source +cd /home/git/gitlab +sudo -u git -H bin/rails console RAILS_ENV=production +``` + +Then run `Feature.enable(:approval_rules)` to enable the feature flag. + +The documentation for the older interface can be accessed +[here](/11.7/ee/user/project/merge_requests/merge_request_approvals.html). + +## Overview + +Merge request approvals enable enforced code review by requiring specified people to approve a merge request before it can be unblocked for merging. + +## Use cases + +1. Enforcing review of all code that gets merged into a repository. +2. Specifying code maintainers for an entire repository. +3. Specifying reviewers for a given proposed code change. +4. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes. + +## Editing approvals + +To edit the merge request approvals: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals**. + +  + +1. Click **Edit**. +1. Search for users or groups that will be [eligible to approve](#eligible-approvers) + merge requests and click the **Add** button to add them as approvers. Note: selecting + approvers is optional. +1. Set the minimum number of required approvals under the **No. approvals required** + box. Note: the minimum can be 0. +1. Click **Update approvers**. + +  + +The steps above are the minimum required to get approvals working in your +merge requests, but there are a couple more options available that might be +suitable to your workflow: + +- Choose whether the default settings can be + [overridden per merge request](#overriding-the-merge-request-approvals-default-settings) +- Choose whether [approvals will be reset with new pushed commits](#resetting-approvals-on-push) + +## Editing approvals **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. + +For GitLab Premium, [multiple approver rules](#multiple-approval-rules-premium) can be configured. To configure the merge +request approval rules: + +1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. +1. Click **Add approvers** to create a new approval rule. +1. Just like in [GitLab Starter](#editing-approvals), select the approval members and aprovals required. +1. Give the approval rule a name that describes the set of approvers selected. +1. Click **Add approvers** to submit the new rule. + +  + +## Multiple approval rules **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. + +For GitLab Premium, a merge request's overall approval status is determined by a set of rules. Each rule contains: + +- A set of [eligible approvers](#eligible-approvers). +- A minimum number of approvals required. + +When an [eligible approver](#eligible-approvers) approves a merge request, it will reduce the number of approvals left for +all rules that the approver belongs to. + + + +If no approval rules are set, then the overall minimum number of approvals required can be configured. With no approval rules, +any [eligible approver](#eligible-approvers) may approve. + +## Eligible approvers + +The following can approve merge requests: + +- Users being added as approvers at project or merge request level. +- [Code owners](../code_owners.md) related to the merge request ([introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5). + +An individual user can be added as an approver for a project if they are a member of: + +- The project. +- The project's immediate parent group. +- A group that has access to the project via a [share](../members/share_project_with_groups.md). + +A group can also be added as an approver. [In the future](https://gitlab.com/gitlab-org/gitlab-ee/issues/2048), +group approvers will be restricted. + +If a user is added as an individual approver and is also part of a group approver, +then that user is just counted once. The merge request author and users who have authored +commits in the merge request do not count as eligible approvers, +unless [self-approval] is explicitly enabled on the project settings. + +### Implicit approvers + +If the number of required approvals is greater than the number of approvers, +other users will become implicit approvers to fill the gap. +Those implicit approvers include members of the given project with Developer role or higher. + +## Adding or removing an approval + +If approvals are activated for the given project, when a user visits an open +merge request, depending on their [eligibility](#eligible-approvers), one of +the following is possible: + +- **They are not an eligible approver**: They cannot do anything with respect + to approving this merge request. + +- **They have not approved this merge request**: + + - If the required number of approvals has _not_ been yet met, they can approve + it by clicking the displayed **Approve** button. +  + - If the required number of approvals has already been met, they can still + approve it by clicking the displayed **Approve additionally** button. +  + +- **They have already approved this merge request**: They can remove their approval. + +  + +NOTE: **Note:** +The merge request author is only allowed to approve their own merge request +if [self-approval] is enabled on the project settings. + +For a given merge request, if the approval restrictions have been satisfied, +the merge request is unblocked and can be merged. +Note, that meeting the required number of approvals is a necessary, but not +sufficient condition for unblocking a merge request from being merged. There +are other conditions that may block it, such as merge conflicts, +[pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved) +or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). + +## Code Owners approvals **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. + +It is possible to require at least one approval for each entry in the +[`CODEOWNERS` file](../code_owners.md) that matches a file changed in +the merge request. To enable this feature: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals**. +1. Tick the **Require approval from code owners** checkbox + checkbox. +1. Click **Save changes**. + +When this feature is enabled, all merge requests will need approval +from one code owner per matched rule before it can be merged. + +## Overriding the merge request approvals default settings + +> Introduced in GitLab Enterprise Edition 9.4. + +NOTE: **Note:** +If you are using GitLab Premium, things are a little different with [multiple approval rules](#multiple-approval-rules-premium). +Read the differences [in GitLab Premium when overriding merge request approvals](#overriding-merge-request-approvals-default-settings-premium). + +If approvals are [set at the project level](#editing-approvals), the +default configuration (number of required approvals and approvers) can be +overridden for each merge request in that project. + +One possible scenario would be to to assign a group of approvers at the project +level and change them later when creating or editing the merge request. + +First, you have to enable this option in the project's settings: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals** +1. Tick the "Can override approvers and approvals required per merge request" + checkbox + +  + +1. Click **Save changes** + +NOTE: **Note:** +If approver overriding is enabled +and the project level approvers are changed after a merge request is created, +the merge request retains the previous approvers. +However, the approvers can be changed by [editing the merge request](#overriding-the-merge-request-approvals-default-settings). + +--- + +The default approval settings can now be overridden when creating a +[merge request](index.md) or by editing it after it's been created: + +1. Click **Edit** under the **Approvers** section. +1. Search for users or groups that will be [eligible to approve](#eligible-approvers) + merge requests and click the **Add** button to add them as approvers or + remove existing approvers that were set in the project's settings. +1. If you want to change the number of required approvals, set a new number + in the **No. approvals required** box. +1. Click **Update approvers**. + +There are however some restrictions: + +- The amount of required approvals, if changed, must be greater than the default + set at the project level. This ensures that you're not forced to adjust settings + when someone is unavailable for approval, yet the process is still enforced. + +NOTE: **Note:** +If you are contributing to a forked project, things are a little different. +Read what happens when the +[source and target branches are not the same](#merge-requests-with-different-source-branch-and-target-branch-projects). + +## Overriding merge request approvals default settings **[PREMIUM]** + +In GitLab Premium, when the approval rules are [set at the project level](#editing-approvals-premium), and +**Can override approvers and approvals required per merge request** is checked, there are a few more +restrictions (compared to [GitLab Starter](#overriding-the-merge-request-approvals-default-settings)): + +- Approval rules can be added to an MR with no restriction. +- For project sourced approval rules, editing and removing approvers is not allowed. +- The approvals required of all approval rules is configurable, but if a rule is backed by a project rule, then it is restricted +to the minimum approvals required set in the project's corresponding rule. + +## Resetting approvals on push + +If approvals are [set at the project level](#editing-approvals), +you can choose whether all approvals on a merge request are removed when +new commits are pushed to the source branch of the merge request: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals** +1. Tick the "Remove all approvals in a merge request when new commits are pushed to its source branch" + checkbox + +  + +1. Click **Save changes** + +NOTE: **Note:** +Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) +from the UI. +However, approvals will be reset if the target branch is changed. + +If you want approvals to persist, independent of changes to the merge request, +turn this setting to off by unchecking the box and saving the changes. + +## Allowing merge request authors to approve their own merge requests + +You can allow merge request authors to self-approve merge requests by +enabling it [at the project level](#editing-approvals). Authors +also need to be included in the approvers list in order to be able to +approve their merge request. + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals** +1. Tick the "Enable self approval of merge requests" checkbox +1. Click **Save changes** + +## Merge requests with different source branch and target branch projects + +If the merge request source branch and target branch belong to different +projects (which happens in merge requests in forked projects), everything is +with respect to the target branch's project (typically the original project). +In particular, since the merge request in this case is part of the target +branch's project, the relevant settings are the target project's. The source +branch's project settings are not applicable. Even if you start the merge +request from the source branch's project UI, pay attention to the created merge +request itself. It belongs to the target branch's project. + +[self-approval]: #allowing-merge-request-authors-to-approve-their-own-merge-requests + +## Approver suggestions + +Approvers are suggested for merge requests based on the previous authors of the files affected by the merge request. + +## Filtering merge requests by approvers + +To filter merge requests by an individual approver, you can type (or select from +the dropdown) `approver` and select the user. + + diff --git a/doc/user/project/merge_requests/sast.md b/doc/user/project/merge_requests/sast.md new file mode 100644 index 00000000000..7ebf5ad69ac --- /dev/null +++ b/doc/user/project/merge_requests/sast.md @@ -0,0 +1,71 @@ +# Static Application Security Testing (SAST) **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3775) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. + +NOTE: **4 of the top 6 attacks were application based.** +Download our whitepaper, +["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) +to learn how to protect your organization. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known +vulnerabilities using Static Application Security Testing (SAST). + +You can take advantage of SAST by either [including the CI job](../../../ci/examples/sast.md) in +your existing `.gitlab-ci.yml` file or by implicitly using +[Auto SAST](../../../topics/autodevops/index.md#auto-sast-ultimate) +that is provided by [Auto DevOps](../../../topics/autodevops/index.md). + +Going a step further, GitLab can show the vulnerability list right in the merge +request widget area. + +## Use cases + +- Your code has a potentially dangerous attribute in a class, or unsafe code + that can lead to unintended code execution. +- Your application is vulnerable to cross-site scripting (XSS) attacks that can + be leveraged to unauthorized access to session data + +## Supported languages and frameworks + +The following languages and frameworks are supported. + +| Language / framework | Scan tool | +|-------------------------|----------------------------------------------------------------------------------------| +| .NET | [Security Code Scan](https://security-code-scan.github.io) | +| Any | [Gitleaks](https://github.com/zricethezav/gitleaks), [TruffleHog](https://github.com/dxa4481/truffleHog) and [Diffence](https://github.com/techjacker/diffence) (secret detectors) | +| C/C++ | [Flawfinder](https://www.dwheeler.com/flawfinder/) | +| Go | [Gosec](https://github.com/securego/gosec) | +| Groovy (Ant, Gradle, Maven and SBT) | [find-sec-bugs](https://find-sec-bugs.github.io/) | +| Java (Ant, Gradle, Maven and SBT) | [find-sec-bugs](https://find-sec-bugs.github.io/) | +| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | +| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | +| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | +| Python | [bandit](https://github.com/PyCQA/bandit) | +| Ruby on Rails | [brakeman](https://brakemanscanner.org) | +| Scala (Ant, Gradle, Maven and SBT) | [find-sec-bugs](https://find-sec-bugs.github.io/) | +| Typescript | [TSLint Config Security](https://github.com/webschik/tslint-config-security/) | + +## How it works + +First of all, you need to define a job in your `.gitlab-ci.yml` file that generates the +[SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast-ultimate). +For more information on how the SAST job should look like, check the +example on [Static Application Security Testing with GitLab CI/CD](../../../ci/examples/sast.md). + +GitLab then checks this report, compares the found vulnerabilities between the source and target +branches, and shows the information right on the merge request. + + + +## Security report under pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3776) +in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.6. + +Visit any pipeline page which has a `sast` job and you will be able to see +the security report tab with the listed vulnerabilities (if any). + + diff --git a/doc/user/project/merge_requests/sast_docker.md b/doc/user/project/merge_requests/sast_docker.md new file mode 100644 index 00000000000..70b269046e5 --- /dev/null +++ b/doc/user/project/merge_requests/sast_docker.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'container_scanning.md' +--- + +This document was moved to [another location](container_scanning.md). diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md new file mode 100644 index 00000000000..0ad08da8ff5 --- /dev/null +++ b/doc/user/project/milestones/burndown_charts.md @@ -0,0 +1,70 @@ +# Burndown Charts **[STARTER]** + +> **Notes:** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1540) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1 for project milestones. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5354) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.8 for group milestones. +> - [Added](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6495) to [GitLab Starter](https://about.gitlab.com/pricing/) 11.2 for group milestones. +> - Closed or reopened issues prior to GitLab 9.1 won't have a `closed_at` +> value, so the burndown chart considers them as closed on the milestone +> `start_date`. In that case, a warning will be displayed. + +## Overview + +Burndown Charts are visual representations of the progress of completing a milestone. + + + +At a glance, you see the current state for the completion a given milestone. +Without them, you would have to organize the data from the milestone and plot it +yourself to have the same sense of progress. + +GitLab Starter plots it for you and presents it in a clear and beautiful chart. + +For an overview, check the video demonstration on [Mapping Work Versus Time, With Burndown Charts](https://about.gitlab.com/2017/04/25/mapping-work-to-do-versus-time-with-burndown-charts/). + +## Use cases + +Burndown Charts, in general, are used for tracking and analyzing the completion of +a milestone. Therefore, their use cases are tied to the +[use you are assigning your milestone to](index.md). + +To exemplify, suppose you lead a team of developers in a large company, +and you follow this workflow: + +- Your company set the goal for the quarter to deliver 10 new features for your app + in the upcoming major release. +- You create a milestone, and remind your team to assign that milestone to every new issue + and merge request that's part of the launch of your app. +- Every week, you open the milestone, visualize the progress, identify the gaps, + and help your team to get their work done. +- Every month, you check in with your supervisor, and show the progress of that milestone + from the Burndown Chart. +- By the end of the quarter, your team successfully delivered 100% of that milestone, as + it was taken care of closely throughout the whole quarter. + +## How it works + +A Burndown Chart is available for every project or group milestone that has been attributed a **start +date** and a **due date**. + +Find your project's **Burndown Chart** under **Project > Issues > Milestones**, +and select a milestone from your current ones, while for group's, access the **Groups** dashboard, +select a group, and go through **Issues > Milestones** on the sidebar. + +NOTE: **Note:** +You're able to [promote project](https://docs.gitlab.com/ee/user/project/milestones/#promoting-project-milestones-to-group-milestones) to group milestones and still see the **Burndown Chart** for them, respecting license limitations. + +The chart indicates the project's progress throughout that milestone (for issues assigned to it). + +In particular, it shows how many issues were or are still open for a given day in the +milestone's corresponding period. + +The Burndown Chart tracks when issues were created and when they were last closed—not their full history. For each day, it takes the number of issues still open and issues created that day and subtracts the number of issues closed that day. +**Issues that were created and assigned a milestone before its start date—and remain open as of the start date—are considered as having been opened on the start date**. Therefore, when the milestone start date is changed the number of opened issues on each day may change. +Reopened issues are +considered as having been opened on the day after they were last closed. + +The Burndown Chart can also be toggled to display the cumulative open issue +weight for a given day. When using this feature, make sure issue weights have +been properly assigned, since an open issue with no weight adds zero to the +cumulative value. diff --git a/doc/user/project/milestones/img/burndown_chart.png b/doc/user/project/milestones/img/burndown_chart.png Binary files differnew file mode 100644 index 00000000000..e06b24f9907 --- /dev/null +++ b/doc/user/project/milestones/img/burndown_chart.png diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index e6033ca8655..0dfd87f91a5 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -83,7 +83,12 @@ From the project issue/merge request list pages and the group issue/merge reques ### Filtering in issue boards -From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [search and filter bar](../../search/index.md#issue-boards). +- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [search and filter bar](../../search/index.md#issue-boards). +- From [group issue boards](../issue_board.md#group-issue-boards), you can filter by only group milestones in the [search and filter bar](../../search/index.md#issue-boards). **[PREMIUM]** +- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [issue board configuration](../issue_board.md#board-with-configuration). **[STARTER]** +- From [group issue boards](../issue_board.md#group-issue-boards) you can filter by only group milestones in the [issue board configuration](../issue_board.md#board-with-configuration). **[PREMIUM]** + + ### Special milestone filters @@ -108,6 +113,7 @@ Not all features in the project milestone view are available in the group milest | Start date and due date | ✓ | ✓ | | Total issue time spent | ✓ | ✓ | | Total issue weight | ✓ | | +| Burndown chart | ✓ | ✓ | The milestone view shows the title and description. @@ -118,6 +124,17 @@ These features are only available for project milestones and not group milestone - Issues assigned to the milestone are displayed in three columns: Unstarted issues, ongoing issues, and completed issues. - Merge requests assigned to the milestone are displayed in four columns: Work in progress merge requests, waiting for merge, rejected, and closed. - Participants and labels that are used in issues and merge requests that have the milestone assigned are displayed. +- [Burndown chart](#project-burndown-charts-starter). + +### Project Burndown Charts **[STARTER]** + +For project milestones in [GitLab Starter](https://about.gitlab.com/pricing), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. + + + +### Group Burndown Charts **[PREMIUM]** + +For group milestones in [GitLab Premium](https://about.gitlab.com/pricing), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. ### Milestone sidebar diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md new file mode 100644 index 00000000000..a5db3d70bb9 --- /dev/null +++ b/doc/user/project/operations/feature_flags.md @@ -0,0 +1,177 @@ +# Feature Flags **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 11.4. + +CAUTION: **Warning:** +This an _alpha_ feature and is subject to change at any time without +prior notice. + +Feature flags allow you to ship a project in different flavors by +dynamically toggling certain functionality. + +## Overview + +Feature Flags offer a feature toggle system for your application. They enable teams +to achieve Continuous Delivery by deploying new features to production at smaller +batches for controlled testing, separating feature delivery from customer launch. +This helps reducing risk and allows you to easily manage which features to enable. + +GitLab offers a Feature Flags interface that allows you to create, toggle and +remove feature flags. + +## How it works + +Underneath, GitLab uses [unleash](https://github.com/Unleash/unleash), a feature +toggle service. GitLab provides an API where your application can talk to and get the +list of feature flags you set in GitLab. + +The application must be configured to talk to GitLab, so that's up to the +developers to use a compatible [client library](#client-libraries) and +integrate it in their app. + +By setting a flag active or inactive via GitLab, your application will automatically +know which features to enable or disable respectively. + +## Adding a new feature flag + +To add a new feature flag: + +1. Navigate to your project's **Operations > Feature Flags**. +1. Click on the **New Feature Flag** button. +1. Give it a name. + + NOTE: **Note:** + A name can contain only lowercase letters, digits, underscores (`_`) + and dashes (`-`), must start with a letter, and cannot end with a dash (`-`) + or an underscore (`_`). + +1. Give it a description (optional, 255 characters max). +1. Define environment [specs](#define-environment-specs). If you want the flag on by default, enable the catch-all [wildcard spec (`*`)](#define-environment-specs) +1. Click **Create feature flag**. + +Once a feature flag is created, the list of existing feature flags will be presented +with ability to edit or remove them. + +To make a feature flag active or inactive, click the pencil icon to edit it, +and toggle the status for each [spec](#define-environment-specs). + + + +## Define environment specs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8621) in GitLab 11.8. + +In general, an application is deployed to multiple environments, such as +production, staging and [review apps](../../../ci/review_apps/index.md). +For example, you may not want to enable a feature flag on production until your QA team has +first confirmed that the feature is working correctly on testing environments. + +To handle these situations, you can enable a feature flag on a particular environment +with [Environment specs](../../../ci/environments.md#scoping-environments-with-specs-premium). +You can define multiple specs per flag so that you can control your feature flag more granularly. + +To define specs for each environment: + +1. Navigate to your project's **Operations > Feature Flags**. +1. Click on the **New Feature Flag** button or edit an existing flag. +1. Set the status of the default [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) (`*`). This status will be used for _all_ environments. +1. If you want to enable/disable the feature on a specific environment, create a new [spec](../../../ci/environments.md#scoping-environments-with-specs-premium) and type the environment name. +1. Set the status of the additional spec. This status takes precedence over the default spec's status since we always use the most specific match available. +1. Click **Create feature flag** or **Update feature flag**. + + + +NOTE: **NOTE** +We'd highly recommend you to use the [Environment](../../../ci/environments.md) +feature in order to quickly assess which flag is enabled per environment. + +## Integrating with your application + +In order to use Feature Flags, you need to first +[get the access credentials](#configuring-feature-flags) from GitLab and then +prepare your application and hook it with a [client library](#client-libraries). + +### Configuring Feature Flags + +To get the access credentials that your application will need to talk to GitLab: + +1. Navigate to your project's **Operations > Feature Flags**. +1. Click on the **Configure** button to see the values: + - **API URL**: URL where the client (application) connects to get a list of feature flags. + - **Instance ID**: Unique token that authorizes the retrieval of the feature flags. + - **Application name**: The name of the running environment. For instance, + if the application runs for production server, application name would be + `production` or similar. This value is used for + [the environment spec evaluation](#define-environment-specs). + +NOTE: **Note:** +The meaning of these fields might change over time. For example, we are not sure +if **Instance ID** will be single token or multiple tokens, assigned to the +**Environment**. Also, **Application name** could describe the version of +application instead of the running environment. + +### Client libraries + +GitLab currently implements a single backend that is compatible with +[Unleash](https://github.com/Unleash/unleash#client-implementations) clients. + +Unleash clients allow the developers to define in the app's code the default +values for flags. Each feature flag evaluation can express the desired +outcome in case the flag isn't present on the provided configuration file. + +Unleash currently offers a number of official SDKs for various frameworks and +a number of community contributed libraries. + +Official clients: + +- [unleash/unleash-client-java](https://github.com/unleash/unleash-client-java) +- [unleash/unleash-client-node](https://github.com/unleash/unleash-client-node) +- [unleash/unleash-client-go](https://github.com/unleash/unleash-client-go) +- [unleash/unleash-client-ruby](https://github.com/unleash/unleash-client-ruby) + +Community contributed clients: + +- [stiano/unleash-client-dotnet](https://github.com/stiano/unleash-client-dotnet) (.Net Core) +- [onybo/unleash-client-core](https://github.com/onybo/unleash-client-core) (.Net Core) +- [aes/unleash-client-python](https://github.com/aes/unleash-client-python) (Python 3) + +### Golang application example + +Here's an example of how to integrate the feature flags in a Golang application: + +```golang +package main + +import ( + "io" + "log" + "net/http" + + "github.com/Unleash/unleash-client-go" +) + +type metricsInterface struct { +} + +func init() { + unleash.Initialize( + unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"), + unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"), + unleash.WithAppName("production"), + unleash.WithListener(&metricsInterface{}), + ) +} + +func helloServer(w http.ResponseWriter, req *http.Request) { + if unleash.IsEnabled("my_feature_name") { + io.WriteString(w, "Feature enabled\n") + } else { + io.WriteString(w, "hello, world!\n") + } +} + +func main() { + http.HandleFunc("/", helloServer) + log.Fatal(http.ListenAndServe(":8080", nil)) +} +``` diff --git a/doc/user/project/operations/img/feature_flags_list.png b/doc/user/project/operations/img/feature_flags_list.png Binary files differnew file mode 100644 index 00000000000..5313a163fec --- /dev/null +++ b/doc/user/project/operations/img/feature_flags_list.png diff --git a/doc/user/project/operations/img/specs_list.png b/doc/user/project/operations/img/specs_list.png Binary files differnew file mode 100644 index 00000000000..9630c907cfc --- /dev/null +++ b/doc/user/project/operations/img/specs_list.png diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md index b0f9936be5c..0086c15c98a 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -7,5 +7,5 @@ your applications: - Deploy to different [environments](../../../ci/environments.md). - Connect your project to a [Kubernetes cluster](../clusters/index.md). - Discover and view errors generated by your applications with [Error Tracking](error_tracking.md). -- Create, toggle, and remove [Feature Flags](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html). **[PREMIUM]** -- [Trace](https://docs.gitlab.com/ee/user/project/operations/tracing.html) the performance and health of a deployed application. **[ULTIMATE]** +- Create, toggle, and remove [Feature Flags](feature_flags.md). **[PREMIUM]** +- [Trace](tracing.md) the performance and health of a deployed application. **[ULTIMATE]** diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md new file mode 100644 index 00000000000..0416e096cf2 --- /dev/null +++ b/doc/user/project/operations/tracing.md @@ -0,0 +1,34 @@ +# Tracing **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/7903) in GitLab Ultimate 11.5. + +Tracing provides insight into the performance and health of a deployed application, +tracking each function or microservice which handles a given request. + +This makes it easy to +understand the end-to-end flow of a request, regardless of whether you are using a monolithic or distributed system. + +## Jaeger tracing + +[Jaeger](https://www.jaegertracing.io/) is an open source, end-to-end distributed +tracing system used for monitoring and troubleshooting microservices-based distributed +systems. + +### Deploying Jaeger + +To learn more about deploying Jaeger, read the official +[Getting Started documentation](https://www.jaegertracing.io/docs/latest/getting-started/). +There is an easy to use [all-in-one Docker image](https://www.jaegertracing.io/docs/latest/getting-started/#AllinoneDockerimage), +as well as deployment options for [Kubernetes](https://github.com/jaegertracing/jaeger-kubernetes) +and [OpenShift](https://github.com/jaegertracing/jaeger-openshift). + +### Enabling Jaeger + +GitLab provides an easy way to open the Jaeger UI from within your project: + +1. [Set up Jaeger](#deploying-jaeger) and configure your application using one of the + [client libraries](https://www.jaegertracing.io/docs/latest/client-libraries/). +1. Navigate to your project's **Settings > Operations** and provide the Jaeger URL. +1. Click **Save changes** for the changes to take effect. +1. You can now visit **Operations > Tracing** in your project's sidebar and + GitLab will redirect you to the configured Jaeger URL.
\ No newline at end of file diff --git a/doc/user/project/packages/img/maven_package_view.png b/doc/user/project/packages/img/maven_package_view.png Binary files differnew file mode 100644 index 00000000000..2eb4b6f76b4 --- /dev/null +++ b/doc/user/project/packages/img/maven_package_view.png diff --git a/doc/user/project/packages/img/npm_package_view.png b/doc/user/project/packages/img/npm_package_view.png Binary files differnew file mode 100644 index 00000000000..8baf7d0ef9f --- /dev/null +++ b/doc/user/project/packages/img/npm_package_view.png diff --git a/doc/user/project/packages/maven.md b/doc/user/project/packages/maven.md new file mode 100644 index 00000000000..266225fdb8d --- /dev/null +++ b/doc/user/project/packages/maven.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'maven_repository.md' +--- + +This document was moved to [another location](maven_repository.md). diff --git a/doc/user/project/packages/maven_packages.md b/doc/user/project/packages/maven_packages.md new file mode 100644 index 00000000000..266225fdb8d --- /dev/null +++ b/doc/user/project/packages/maven_packages.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'maven_repository.md' +--- + +This document was moved to [another location](maven_repository.md). diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md new file mode 100644 index 00000000000..b62b79162a2 --- /dev/null +++ b/doc/user/project/packages/maven_repository.md @@ -0,0 +1,340 @@ +# GitLab Maven Repository **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811) in + [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. + +With the GitLab [Maven](https://maven.apache.org) Repository, every +project can have its own space to store its Maven artifacts. + + + +## Enabling the Maven Repository + +NOTE: **Note:** +This option is available only if your GitLab administrator has +[enabled support for the Maven repository](../../../administration/packages.md). + +After the Packages feature is enabled, the Maven Repository will be available for +all new projects by default. To enable it for existing projects, or if you want +to disable it: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Find the Packages feature and enable or disable it. +1. Click on **Save changes** for the changes to take effect. + +You should then be able to see the **Packages** section on the left sidebar. +Next, you must configure your project to authorize with the GitLab Maven +repository. + +## Authenticating to the GitLab Maven Repository + +If a project is private or you want to upload Maven artifacts to GitLab, +credentials will need to be provided for authorization. Support is available for +[personal access tokens](#authenticating-with-a-personal-access-token) and +[CI job tokens](#authenticating-with-a-ci-job-token). + +### Authenticating with a personal access token + +To authenticate with a [personal access token](../../profile/personal_access_tokens.md), +add a corresponding section to your +[`settings.xml`](https://maven.apache.org/settings.html) file: + +```xml +<settings> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Private-Token</name> + <value>REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> +</settings> +``` + +You should now be able to upload Maven artifacts to your project. + +### Authenticating with a CI job token + +If you're using Maven with GitLab CI/CD, a CI job token can be used instead +of a personal access token. + +To authenticate with a CI job token, add a corresponding section to your +[`settings.xml`](https://maven.apache.org/settings.html) file: + +```xml +<settings> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Job-Token</name> + <value>${env.CI_JOB_TOKEN}</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> +</settings> +``` + +You can read more on +[how to create Maven packages using GitLab CI/CD](#creating-maven-packages-with-gitlab-cicd). + +## Configuring your project to use the GitLab Maven repository URL + +To download and upload packages from GitLab, you need a `repository` and +`distributionManagement` section in your `pom.xml` file. + +Depending on your workflow and the amount of Maven packages you have, there are +3 ways you can configure your project to use the GitLab endpoint for Maven packages: + +- **Project level**: Useful when you have few Maven packages which are not under + the same GitLab group. +- **Group level**: Useful when you have many Maven packages under the same GitLab + group. +- **Instance level**: Useful when you have many Maven packages under different + GitLab groups or on their own namespace. + +NOTE: **Note:** +In all cases, you need a project specific URL for uploading a package in +the `distributionManagement` section. + +### Project level Maven endpoint + +The example below shows how the relevant `repository` section of your `pom.xml` +would look like: + +```xml +<repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> +</repositories> +<distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </snapshotRepository> +</distributionManagement> +``` + +The `id` must be the same with what you +[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). + +Replace `PROJECT_ID` with your project ID which can be found on the home page +of your project. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +NOTE: **Note:** +For retrieving artifacts, you can use either the +[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project +(e.g., `group%2Fproject`) or the project's ID (e.g., `42`). However, only the +project's ID can be used for uploading. + +### Group level Maven endpoint + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8798) in GitLab Premium 11.7. + +If you rely on many packages, it might be inefficient to include the `repository` section +with a unique URL for each package. Instead, you can use the group level endpoint for +all your Maven packages stored within one GitLab group. Only packages you have access to +will be available for download. + +The group level endpoint works with any package names, which means the you +have the flexibility of naming compared to [instance level endpoint](#instance-level-maven-endpoint). +However, GitLab will not guarantee the uniqueness of the package names within +the group. You can have two projects with the same package name and package +version. As a result, GitLab will serve whichever one is more recent. + +The example below shows how the relevant `repository` section of your `pom.xml` +would look like. You still need a project specific URL for uploading a package in +the `distributionManagement` section: + +```xml +<repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/groups/my-group/-/packages/maven</url> + </repository> +</repositories> +<distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </snapshotRepository> +</distributionManagement> +``` + +The `id` must be the same with what you +[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). + +Replace `my-group` with your group name and `PROJECT_ID` with your project ID +which can be found on the home page of your project. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +NOTE: **Note:** +For retrieving artifacts, you can use either the +[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project +(e.g., `group%2Fproject`) or the project's ID (e.g., `42`). However, only the +project's ID can be used for uploading. + +### Instance level Maven endpoint + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8274) in GitLab Premium 11.7. + +If you rely on many packages, it might be inefficient to include the `repository` section +with a unique URL for each package. Instead, you can use the instance level endpoint for +all maven packages stored in GitLab and the packages you have access to will be available +for download. + +Note that **only packages that have the same path as the project** are exposed via +the instance level endpoint. + +| Project | Package | Instance level endpoint available | +| ------- | ------- | --------------------------------- | +| `foo/bar` | `foo/bar/1.0-SNAPSHOT` | Yes | +| `gitlab-org/gitlab-ce` | `foo/bar/1.0-SNAPSHOT` | No | +| `gitlab-org/gitlab-ce` | `gitlab-org/gitlab-ce/1.0-SNAPSHOT` | Yes | + +The example below shows how the relevant `repository` section of your `pom.xml` +would look like. You still need a project specific URL for uploading a package in +the `distributionManagement` section: + +```xml +<repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/packages/maven</url> + </repository> +</repositories> +<distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + </snapshotRepository> +</distributionManagement> +``` + +The `id` must be the same with what you +[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). + +Replace `PROJECT_ID` with your project ID which can be found on the home page +of your project. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +NOTE: **Note:** +For retrieving artifacts, you can use either the +[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project +(e.g., `group%2Fproject`) or the project's ID (e.g., `42`). However, only the +project's ID can be used for uploading. + +## Uploading packages + +Once you have set up the [authentication](#authenticating-to-the-gitlab-maven-repository) +and [configuration](#configuring-your-project-to-use-the-gitlab-maven-repository-url), +test to upload a Maven artifact from a project of yours: + +```sh +mvn deploy +``` + +You can then navigate to your project's **Packages** page and see the uploaded +artifacts or even delete them. + +## Creating Maven packages with GitLab CI/CD + +Once you have your repository configured to use the GitLab Maven Repository, +you can configure GitLab CI/CD to build new packages automatically. The example below +shows how to create a new package each time the `master` branch is updated: + +1. Create a `ci_settings.xml` file that will serve as Maven's `settings.xml` file. + Add the server section with the same id you defined in your `pom.xml` file. + For example, in our case it's `gitlab-maven`: + + ```xml + <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Job-Token</name> + <value>${env.CI_JOB_TOKEN}</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> + </settings> + ``` + +1. Make sure your `pom.xml` file includes the following: + + ```xml + <repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </repository> + </repositories> + <distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </snapshotRepository> + </distributionManagement> + ``` + + TIP: **Tip:** + You can either let Maven utilize the CI environment variables or hardcode your project's ID. + +1. Add a `deploy` job to your `.gitlab-ci.yml` file: + + ```yaml + deploy: + image: maven:3.3.9-jdk-8 + script: + - 'mvn deploy -s ci_settings.xml' + only: + - master + ``` + +1. Push those files to your repository. + +The next time the `deploy` job runs, it will copy `ci_settings.xml` to the +user's home location (in this case the user is `root` since it runs in a +Docker container), and Maven will utilize the configured CI +[environment variables](../../../ci/variables/README.md#predefined-environment-variables). diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md new file mode 100644 index 00000000000..9774e402ef7 --- /dev/null +++ b/doc/user/project/packages/npm_registry.md @@ -0,0 +1,120 @@ +# GitLab NPM Registry **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934) + in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. + +With the GitLab NPM Registry, every +project can have its own space to store NPM packages. + + + +NOTE: **Note:** +Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported. + + +NOTE: **Note:** +As `@group/subgroup/project` is not a valid NPM package name, publishing a package +within a subgroup is not supported yet. + +## Enabling the NPM Registry + +NOTE: **Note:** +This option is available only if your GitLab administrator has +[enabled support for the NPM registry](../../../administration/packages.md). + +After the NPM registry is enabled, it will be available for all new projects +by default. To enable it for existing projects, or if you want to disable it: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Find the Packages feature and enable or disable it. +1. Click on **Save changes** for the changes to take effect. + +You should then be able to see the **Packages** section on the left sidebar. + +Before proceeding to authenticating with the GitLab NPM Registry, you should +get familiar with the package naming convention. + +## Package naming convention + +**Only packages that have the same path as the project** are supported. For + example: + +| Project | Package | Supported | +| ---------------------- | ----------------------- | --------- | +| `foo/bar` | `@foo/bar` | Yes | +| `gitlab-org/gitlab-ce` | `@gitlab-org/gitlab-ce` | Yes | +| `gitlab-org/gitlab-ce` | `@foo/bar` | No | + +Now, you can configure your project to authenticate with the GitLab NPM +Registry. + +## Authenticating to the GitLab NPM Registry + +If a project is private or you want to upload an NPM package to GitLab, +credentials will need to be provided for authentication. Support is available +only for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). + +CAUTION: **2FA not supported:** +Authentication for personal access tokens is not yet supported +([#9140](https://gitlab.com/gitlab-org/gitlab-ee/issues/9140)). If you have 2FA +enabled, you won't be able to authenticate to the GitLab NPM Registry. + +### Authenticating with an OAuth token + +To authenticate with an [OAuth token](../../../api/oauth2.md#resource-owner-password-credentials-flow), +add a corresponding section to your `.npmrc` file: + +```ini +; Set URL for your scoped packages. +; For example package with name `@foo/bar` will use this URL for download +@foo:registry=https://gitlab.com/api/v4/packages/npm/ + +; Add the OAuth token for the scoped packages URL. This will allow you to download +; `@foo/` packages from private projects. +//gitlab.com/api/v4/packages/npm/:_authToken=<your_oauth_token> + +; Add OAuth token for uploading to the registry. Replace <your_project_id> +; with the project you want your package to be uploaded to. +//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_oauth_token> +``` + +Replace `<your_project_id>` with your project ID which can be found on the home page +of your project and `<your_oauth_token>` with your OAuth token. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +You should now be able to download and upload NPM packages to your project. + +## Uploading packages + +Before you will be able to upload a package, you need to specify the registry +for NPM. To do this, add the following section to the bottom of `package.json`: + +```json + "publishConfig": { + "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" + } +``` + +Replace `<your_project_id>` with your project ID, which can be found on the home +page of your project, and replace `@foo` with your own scope. + +If you have a self-hosted GitLab installation, replace `gitlab.com` with your +domain name. + +Once you have enabled it and set up [authentication](#authenticating-to-the-gitlab-npm-registry), +you can upload an NPM package to your project: + +```sh +npm publish +``` + +You can then navigate to your project's **Packages** page and see the uploaded +packages or even delete them. + +## Uploading a package with the same version twice + +If you upload a package with a same name and version twice, GitLab will show +both packages in the UI, but the GitLab NPM Registry will expose the most recent +one as it supports only one package per version for `npm install`. diff --git a/doc/user/project/pages/img/icons/click.png b/doc/user/project/pages/img/icons/click.png Binary files differindex a534ae29e0f..62a997a7591 100644 --- a/doc/user/project/pages/img/icons/click.png +++ b/doc/user/project/pages/img/icons/click.png diff --git a/doc/user/project/pages/img/icons/fork.png b/doc/user/project/pages/img/icons/fork.png Binary files differindex 8a3aa46eb37..1ae8fa722b7 100644 --- a/doc/user/project/pages/img/icons/fork.png +++ b/doc/user/project/pages/img/icons/fork.png diff --git a/doc/user/project/pages/img/icons/free.png b/doc/user/project/pages/img/icons/free.png Binary files differindex ae455033e94..c74cd90fa1a 100644 --- a/doc/user/project/pages/img/icons/free.png +++ b/doc/user/project/pages/img/icons/free.png diff --git a/doc/user/project/pages/img/icons/lock.png b/doc/user/project/pages/img/icons/lock.png Binary files differindex f4c35c84112..f7f32fded45 100644 --- a/doc/user/project/pages/img/icons/lock.png +++ b/doc/user/project/pages/img/icons/lock.png diff --git a/doc/user/project/pages/img/icons/monitor.png b/doc/user/project/pages/img/icons/monitor.png Binary files differindex 8bad059a74c..ce27b7e177e 100644 --- a/doc/user/project/pages/img/icons/monitor.png +++ b/doc/user/project/pages/img/icons/monitor.png diff --git a/doc/user/project/pages/img/icons/terminal.png b/doc/user/project/pages/img/icons/terminal.png Binary files differindex 377eeb4edc6..5a711f05c4e 100644 --- a/doc/user/project/pages/img/icons/terminal.png +++ b/doc/user/project/pages/img/icons/terminal.png diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 3eb8123144f..91a85a36a53 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -15,12 +15,10 @@ By default, a protected branch does four simple things: - it prevents **anyone** from force pushing to the branch - it prevents **anyone** from deleting the branch -See the [Changelog](#changelog) section for changes over time. +>**Note**: +A GitLab admin is allowed to push to the protected branches. -> ->Additional functionality for GitLab Enterprise Edition: -> ->- Restrict push and merge access to [certain users][ee-restrict] +See the [Changelog](#changelog) section for changes over time. ## Configuring protected branches @@ -68,6 +66,21 @@ dropdown list in the "Already protected" area. If you don't choose any of those options while creating a protected branch, they are set to "Maintainers" by default. +## Restricting push and merge access to certain users **[STARTER]** + +> This feature was [introduced][ce-5081] in [GitLab Starter][ee] 8.11. + +With GitLab Enterprise Edition you can restrict access to protected branches +by choosing a role (Maintainers, Developers) as well as certain users. From the +dropdown menu select the role and/or the users you want to have merge or push +access. + + + +Click **Protect** and the branch will appear in the "Protected branch" list. + + + ## Wildcard protected branches > [Introduced][ce-4665] in GitLab 8.10. @@ -169,3 +182,4 @@ for details about the pipelines security model. [ce-21393]: https://gitlab.com/gitlab-org/gitlab-ce/issues/21393 [ee-restrict]: http://docs.gitlab.com/ee/user/project/protected_branches.html#restricting-push-and-merge-access-to-certain-users [perm]: ../permissions.md +[ee]: https://about.gitlab.com/pricing/ diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 392e72dcc5c..4c35be39224 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -45,13 +45,15 @@ discussions, and descriptions: | `/remove_due_date` | Remove due date | ✓ | | | `/weight 0,1,2, ...` | Set weight **[STARTER]** | ✓ | | | `/clear_weight` | Clears weight **[STARTER]** | ✓ | | -| `/epic <group&epic | Epic URL>` | Add to epic **[ULTIMATE]** | ✓ | | +| `/epic <&epic | group&epic | Epic URL>` | Add to epic **[ULTIMATE]** | ✓ | | | `/remove_epic` | Removes from epic **[ULTIMATE]** | ✓ | | +| `/promote` | Promote issue to epic **[ULTIMATE]** | ✓ | | | `/confidential` | Make confidential | ✓ | | | `/duplicate #issue` | Mark this issue as a duplicate of another issue | ✓ | | `/move path/to/project` | Move this issue to another project | ✓ | | | `/target_branch <Local branch Name>` | Set target branch | | ✓ | | `/wip` | Toggle the Work In Progress status | | ✓ | +| `/approve` | Approve the merge request | | ✓ | | `/merge` | Merge (when pipeline succeeds) | | ✓ | | `/create_merge_request <branch name>` | Create a new merge request starting from the current issue | ✓ | | diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box.png b/doc/user/project/repository/branches/img/branch_filter_search_box.png Binary files differindex 5dc7eccf189..5dc300cf24e 100644 --- a/doc/user/project/repository/branches/img/branch_filter_search_box.png +++ b/doc/user/project/repository/branches/img/branch_filter_search_box.png diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 6495ede42e0..3260a355fdc 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -264,7 +264,7 @@ To remove a GPG key from your account: ## Rejecting commits that are not signed **[PREMIUM]** You can configure your project to reject commits that aren't GPG-signed -via [push rules](https://docs.gitlab.com/ee/push_rules/push_rules.html). +via [push rules](../../../../push_rules/push_rules.md). ## GPG signing API diff --git a/doc/user/project/repository/img/repository_cleanup.png b/doc/user/project/repository/img/repository_cleanup.png Binary files differindex bda40d3e193..e343f23ac27 100644 --- a/doc/user/project/repository/img/repository_cleanup.png +++ b/doc/user/project/repository/img/repository_cleanup.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 22d912cd9d1..c6606bea10e 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -220,14 +220,9 @@ Select branches to compare using the [branch filter search box](branches/index.m Find it under your project's **Repository > Compare**. -## Locked files +## Locked files **[PREMIUM]** -> Available in [GitLab Premium](https://about.gitlab.com/pricing/). - -Lock your files to prevent any conflicting changes. - -[File Locking](https://docs.gitlab.com/ee/user/project/file_lock.html) is available only in -[GitLab Premium](https://about.gitlab.com/pricing/). +[Lock your files](../file_lock.md) to prevent any conflicting changes. ## Repository's API diff --git a/doc/user/project/security_dashboard.md b/doc/user/project/security_dashboard.md new file mode 100644 index 00000000000..b7294642150 --- /dev/null +++ b/doc/user/project/security_dashboard.md @@ -0,0 +1,35 @@ +# Project Security Dashboard **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.1. + +The Security Dashboard displays the latest security reports for your project. +Use it to find and fix vulnerabilities affecting the [default branch](./repository/branches/index.md#default-branch). + + + +## How it works? + +To benefit from the Security Dashboard you must first configure the [Security Reports](merge_requests/index.md#security-reports-ultimate). + +The Security Dashboard will then list security vulnerabilities from the latest pipeline run on the default branch (e.g., `master`). + +You will also be able to interact with the reports [the same way you can on a merge request](merge_requests/index.md#interacting-with-security-reports-ultimate). + +## Keeping the Security Dashboard updated + +The Security Dashboard displays information from the results of the most recent security scan on the default branch. Security scans are performed every time the branch is updated. + +If the default branch is updated infrequently, scans are run infrequently and the information on the Security Dashboard can become outdated as new vulnerabilities are discovered. + +To ensure the information on the Security Dashboard is regularly updated, configure a [scheduled pipeline](pipelines/schedules.md) to run a daily security scan. This will update the information displayed on the Security Dashboard regardless of how often the default branch is updated. + +A daily security scan can be configured to only execute jobs that to relate to security. For more information on configuring security-related jobs, see: + +- [Static Application Security Testing](merge_requests/sast.md) and [example](../../ci/examples/sast.md). +- [Dynamic Application Security Testing](merge_requests/dast.md) and [example](../../ci/examples/dast.md). +- [Dependency Scanning](merge_requests/dependency_scanning.md) and [example](../../ci/examples/dependency_scanning.md). +- [Container Scanning](merge_requests/container_scanning.md) and [example](../../ci/examples/container_scanning.md). + +### Security scans using Auto DevOps + +When using [Auto DevOps](../../topics/autodevops/index.md), use [special environment variables](../../topics/autodevops/index.md#environment-variables) to configure daily security scans. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md new file mode 100644 index 00000000000..1a582164d03 --- /dev/null +++ b/doc/user/project/service_desk.md @@ -0,0 +1,124 @@ +# Service Desk **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/149) in [GitLab Premium 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#service-desk-eep). + +## Overview + +Service Desk is a module that allows your team to connect directly +with any external party through email right inside of GitLab; no external tools required. +An ongoing conversation right where your software is built ensures that user feedback ends +up directly where it's needed, helping you build the right features to solve your users' +real problems. + +With Service Desk, you can provide efficient email support to your customers, who can now +email you bug reports, feature requests, or general feedback that will all end up in your +GitLab project as new issues. In turn, your team can respond straight from the project. + +As Service Desk is built right into GitLab itself, the complexity and inefficiencies +of multiple tools and external integrations are eliminated, significantly shortening +the cycle time from feedback to software update. + +For an overview, check the video demonstration on [GitLab Service Desk](https://about.gitlab.com/2017/05/09/demo-service-desk/). + +## Use cases + +For instance, let's assume you develop a game for iOS or Android. +The codebase is hosted in your GitLab instance, built and deployed +with GitLab CI. + +Here's how Service Desk will work for you: + +1. You'll provide a project-specific email address to your paying customers, who can email you directly from within the app +1. Each email they send creates an issue in the appropriate project +1. Your team members navigate to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues +1. Your team communicates back and forth with the customer to understand the request +1. Your team starts working on implementing code to solve your customer's problem +1. When your team finishes the implementation, whereupon the merge request is merged and the issue is closed automatically +1. The customer will have been attended successfully via email, without having real access to your GitLab instance +1. Your team saved time by not having to leave GitLab (or setup any integrations) to follow up with your customer + +## How it works + +GitLab Service Desk is a simple way to allow people to create issues in your +GitLab instance without needing their own user account. + +It provides a unique email address for end users to create issues in a project, +and replies can be sent either through the GitLab interface or by email. End +users will only see the thread through email. + +## Configuring Service Desk + +> **Note:** +Service Desk is enabled on GitLab.com. If you're a +[Silver subscriber](https://about.gitlab.com/gitlab-com/), +you can skip the step 1 below; you only need to enable it per project. + +1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. This must + support [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing). +2. Navigate to your project's **Settings** and scroll down to the **Service Desk** + section. +3. If you have the correct access and an Premium license, + you will see an option to set up Service Desk: + +  + +4. Checking that box will enable Service Desk for the project, and show a + unique email address to email issues to the project. These issues will be + [confidential](issues/confidential_issues.md), so they will only be visible to project members. + + **Warning**: this email address can be used by anyone to create an issue on + this project, whether or not they have access to your GitLab instance. + We recommend **putting this behind an alias** so that it can be changed if + needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab instance to add spam + checking to this service. Unblocked email spam would result in many spam + issues being created, and may disrupt your GitLab service. + +  + + _In GitLab 11.7, we updated the format of the generated email address. + However the older format is still supported, allowing existing aliases + or contacts to continue working._ + + +5. Service Desk is now enabled for this project! You should be able to access it from your project's navigation **Issue submenu**: + +  + +## Using Service Desk + +### As an end user (issue creator) + +To create a Service Desk issue, an end user doesn't need to know anything about +the GitLab instance. They just send an email to the address they are given, and +receive an email back confirming receipt: + + + +This also gives the end user an option to unsubscribe. + +If they don't choose to unsubscribe, then any new comments added to the issue +will be sent as emails: + + + +And any responses they send will be displayed in the issue itself. + +### As a responder to the issue + +For responders to the issue, everything works as usual. They'll see a familiar looking +issue tracker, where they can see issues created via customer support requests and +filter and interact with them just like other GitLab issues. + + + +Messages from the end user will show as coming from the special Support Bot user, but apart from that, +you can read and write comments as you normally do: + + + +> Note that the project's visibility (private, internal, public) does not affect Service Desk. + +### Support Bot user + +Behind the scenes, Service Desk works by the special Support Bot user creating issues. This user +does not count toward the license limit count. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index d5f4a7fd4ac..16cd1f2c14e 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -42,9 +42,9 @@ Set up your project's merge request settings:  -### Service Desk +### Service Desk **[PREMIUM]** -Enable [Service Desk](https://docs.gitlab.com/ee/user/project/service_desk.html) for your project to offer customer support. Service Desk is available in [GitLab Premium](https://about.gitlab.com/pricing/). +Enable [Service Desk](../service_desk.md) for your project to offer customer support. ### Export project @@ -128,3 +128,7 @@ namespace if needed. ### Error Tracking Configure Error Tracking to discover and view [Sentry errors within GitLab](../operations/error_tracking.md). + +### Jaeger tracing + +Add the URL of a Jaeger server to allow your users to [easily access the Jaeger UI from within GitLab](../operations/tracing.md). diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 46a1b2bc3aa..2a2507d98a3 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -128,5 +128,123 @@ IDE. An example `package.json` is below. } ``` +## Interactive Web Terminals for the Web IDE **[ULTIMATE ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. + +CAUTION: **Warning:** +Interactive Web Terminals for the Web IDE is currently in **Beta**. + +[Interactive web terminals](../../../ci/interactive_web_terminal/index.md) +give the user access to a terminal to interact with the Runner directly from +GitLab, including through the Web IDE. + +Only project [**maintainers**](../../permissions.md#project-members-permissions) +can run Interactive Web Terminals through the Web IDE. + +CAUTION: **Warning:** +GitLab.com [does not support Interactive Web Terminals yet](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611). +Shared Runners in private instances are not supported either. + +### Runner configuration + +Some things need to be configured in the runner for the interactive web terminal +to work: + +- The Runner needs to have + [`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section). +- If you are using a reverse proxy with your GitLab instance, web terminals need to be + [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **[ULTIMATE ONLY]** + +If you have the terminal open and the job has finished with its tasks, the +terminal will block the job from finishing for the duration configured in +[`[session_server].terminal_max_retention_time`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) +until you close the terminal window. + +NOTE: **Note:** Not all executors are +[supported](https://docs.gitlab.com/runner/executors/#compatibility-chart) + +### Web IDE configuration file + +In order to enable the Web IDE terminals you need to create the file +`.gitlab/.gitlab-webide.yml` inside the repository's root. This +file is fairly similar to the [CI configuration file](../../../ci/yaml/README.md) +syntax but with some restrictions: + +- No global blocks can be defined (ie: `before_script` or `after_script`) +- Only one job named `terminal` can be added to this file. +- Only the keywords `image`, `services`, `tags`, `before_script`, `script`, and +`variables` are allowed to be used to configure the job. +- To connect to the interactive terminal, the `terminal` job must be still alive +and running, otherwise the terminal won't be able to connect to the job's session. +By default the `script` keyword has the value `sleep 60` to prevent +the job from ending and giving the Web IDE enough time to connect. This means +that, if you override the default `script` value, you'll have to add a command +which would keep the job running, like `sleep`. + +In the code below there is an example of this configuration file: + +```yaml +terminal: + before_script: + - apt-get update + script: sleep 60 + variables: + RAILS_ENV: "test" + NODE_ENV: "test" +``` + +Once the terminal has started, the console will be displayed and we could access +the project repository files. + +**Important**. The terminal job is branch dependant. This means that the +configuration file used to trigger and configure the terminal will be the one in +the selected branch of the Web IDE. + +If there is no configuration file in a branch, an error message will be shown. + +### Running Interactive Terminals in the Web IDE + +If Interactive Terminals are available for the current user, the **Terminal** button +will be visible in the right sidebar of the Web IDE. Click this button to open +or close the terminal tab. + +Once open, the tab will show the **Start Web Terminal** button. This button may +be disabled if the environment is not configured correctly. If so, a status +message will describe the issue. Here are some reasons why **Start Web Terminal** +may be disabled: + +- `.gitlab/.gitlab-webide.yml` does not exist or is set up incorrectly. +- No active private runners are available for the project. + +If active, clicking the **Start Web Terminal** button will load the terminal view +and start connecting to the runner's terminal. At any time, the **Terminal** tab +can be closed and reopened and the state of the terminal will not be affected. + +When the terminal is started and is successfully connected to the runner, then the +runner's shell prompt will appear in the terminal. From here, you can enter +commands that will be executed within the runner's environment. This is similar +to running commands in a local terminal or through SSH. + +While the terminal is running, it can be stopped by clicking **Stop Terminal**. +This will disconnect the terminal and stop the runner's terminal job. From here, +click **Restart Terminal** to start a new terminal session. + +### Limitations + +Interactive Terminals is in a beta phase and will continue to be improved upon in upcoming +releases. In the meantime, please note that the user is limited to having only one +active terminal at a time. + +### Troubleshooting + +- If the terminal's text is gray and unresponsive, then the terminal has stopped + and it can no longer be used. A stopped terminal can be restarted by clicking + **Restart Terminal**. +- If the terminal displays **Connection Failure**, then the terminal could not + connect to the runner. Please try to stop and restart the terminal. If the + problem persists, double check your runner configuration. + + [ce]: https://about.gitlab.com/pricing/ [ee]: https://about.gitlab.com/pricing/ |
