diff options
| author | Marcel Amirault <ravlen@gmail.com> | 2019-05-05 15:37:18 +0000 |
|---|---|---|
| committer | Achilleas Pipinellis <axil@gitlab.com> | 2019-05-05 15:37:18 +0000 |
| commit | 9991d3948b456fae7cf8023cd453c4a01826ae13 (patch) | |
| tree | 7d3a0ee714411106a799d59b8eb1cff8fe0d01be /doc/user/project | |
| parent | 07c0a511b72446c443bffd48c75312ce0d5e677c (diff) | |
| download | gitlab-ce-9991d3948b456fae7cf8023cd453c4a01826ae13.tar.gz | |
Docs: Merge EE doc/user/project/*.md to CE
Diffstat (limited to 'doc/user/project')
35 files changed, 673 insertions, 10 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..51b86a68c7b --- /dev/null +++ b/doc/user/project/ci_cd_for_external_repo.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html). 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..2f2a9c5eec3 --- /dev/null +++ b/doc/user/project/deploy_boards.md @@ -0,0 +1,132 @@ +# 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](../../ci/yaml/README.md#whenmanual) 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 Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` + and `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` are applied to the + deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` and + `$CI_PROJECT_PATH_SLUG` are the values of the CI variables. This is so we can + lookup the proper environment in a cluster/namespace which may have more + than one. These resources should be contained in the namespace defined in + the Kubernetes service setting. You can use an [Autodeploy] `.gitlab-ci.yml` + template which has predefined stages and commands to use, and automatically + applies the annotations. Each project will need to have a unique namespace in + Kubernetes as well. The image below demonstrates how this is shown inside + Kubernetes. + + NOTE: **Note:** + The Kubernetes label of `app` is deprecated and may be removed in next major + release, GitLab 12.0. + +  + +Once all of the above are set up and the pipeline has run at least once, +navigate to the environments page under **Operations > Environments**. + +Deploy Boards are visible by default. You can explicitly click +the triangle next to their respective environment name in order to hide them. +GitLab will then query Kubernetes for the state of each pod (e.g., waiting, +deploying, finished, unknown), and the Deploy Board status will finally appear. + +GitLab will only display a Deploy Board for top-level environments. Foldered +environments like `review/*` (usually used for [Review Apps]) won't have a +Deploy Board attached to them. + +## Canary Deployments + +A popular CI strategy, where a small portion of the fleet is updated to the new +version of your application. + +[Read more about Canary Deployments.](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" +[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..19785c74d07 --- /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/key_value_labels.png b/doc/user/project/img/key_value_labels.png Binary files differnew file mode 100644 index 00000000000..bec901f127f --- /dev/null +++ b/doc/user/project/img/key_value_labels.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/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/index.md b/doc/user/project/index.md index 64139f9dbe9..6b3b40bf9f8 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-starter): 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](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html): 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. **[ULTIMATE]** - [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](https://docs.gitlab.com/ee/user/project/packages/maven_repository.html): your private Maven repository in GitLab. **[PREMIUM]** +- [NPM packages](https://docs.gitlab.com/ee/user/project/packages/npm_registry.html): your private NPM package registry in GitLab. **[PREMIUM]** +- [Code owners](code_owners.md): specify code owners for certain files **[STARTER]** +- [License Management](https://docs.gitlab.com/ee/user/application_security/license_management/index.html): 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 **[PREMIUM]** + +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](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html). + ## Project members Learn how to [add members to your projects](members/index.md). diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 73d61bedde1..bfc3e3a7de0 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -8,9 +8,48 @@ 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. +## Scoped labels **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. + +Scoped labels allow teams to use the simple and familiar feature of labels to +annotate their issues, merge requests, and epics to achieve custom fields and +custom workflow states by leveraging a special label title syntax. + +A scoped label is a kind of label defined only by a special double-colon syntax +in the label’s title, using the format `key::value`. For example: + + + +Two scoped labels with the same key but a different value cannot simultaneeously +apply to an issue, epic, or merge request. For example, if an issue already has `priority::3` +and you apply `priority::2` to it, `priority::3` is automatically removed from the issue. + +An issue, epic, or merge request cannot have two scoped labels with the same key. +For example, if an issue is already labeled `priority::3` and you apply the label `priority::2` to it, +`priority::3` is automatically removed. + +### Workflows with scoped labels **[PREMIUM]** + +Suppose you wanted a custom field in issues to track the platform operating system +that your features target, where each issue should only target one platform. You +would then create labels `platform::iOS`, `platform::Android`, `platform::Linux`, +etc., as necessary. Applying any one of these labels on a given issue would +automatically remove any other existing label that starts with `platform::`. + +The same pattern could be applied to represent the workflow states of your teams. +Suppose you have the labels `workflow::development`, `workflow::review`, and +`workflow::deployed`. If an issue already has the label `workflow::development` +applied, and a developer wanted to advance the issue to `workflow::review`, they +would simply apply that label, and the `workflow::development` label would +automatically be removed. This behavior already exists when you move issues +across label lists in an [issue board](issue_board.md#creating-workflows), but +now, team members who may not be working in an issue board directly would still +be able to advance workflow states consistently in issues themselves. + ## Creating labels >**Note:** @@ -35,6 +74,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 +123,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 +131,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-premium), 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#configurable-issue-boards-starter). **[STARTER]** +- From [group issue boards](issue_board.md#group-issue-boards-premium), you can filter by only group labels in the [issue board configuration](issue_board.md#configurable-issue-boards-starter). **[STARTER]** ## 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..d32d6084b38 --- /dev/null +++ b/doc/user/project/maven_packages.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/user/project/packages/maven_repository.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/user/project/packages/maven_repository.html). diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 2060b5dd4a2..56e8f1731ae 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 2040e2ee004..15eb862b431 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -46,13 +46,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/security_dashboard.md b/doc/user/project/security_dashboard.md new file mode 100644 index 00000000000..43e910b29fe --- /dev/null +++ b/doc/user/project/security_dashboard.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'https://docs.gitlab.com/ee/user/application_security/security_dashboard/index.html' +--- + +This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/security_dashboard/index.html). 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. |
