diff options
Diffstat (limited to 'doc/user/group')
45 files changed, 1142 insertions, 148 deletions
diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 984881ef26c..3c5e820c1ca 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Group-level Kubernetes clusters > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) in GitLab 11.6. @@ -5,41 +9,17 @@ ## Overview -Similar to [project Kubernetes -clusters](../../project/clusters/index.md), Group-level Kubernetes -clusters allow you to connect a Kubernetes cluster to your group, -enabling you to use the same cluster across multiple projects. +Similar to [project-level](../../project/clusters/index.md) and +[instance-level](../../instance/clusters/index.md) Kubernetes clusters, +group-level Kubernetes clusters allow you to connect a Kubernetes cluster to +your group, enabling you to use the same cluster across multiple projects. ## Installing applications -GitLab provides a one-click install for various applications that can be -added directly to your cluster. - -NOTE: **Note:** -Applications will be installed in a dedicated namespace called -`gitlab-managed-apps`. If you have added an existing Kubernetes cluster -with Tiller already installed, you should be careful as GitLab cannot -detect it. In this event, installing Tiller via the applications will -result in the cluster having it twice. This can lead to confusion during -deployments. - -| Application | GitLab version | Description | Helm Chart | -| ----------- | -------------- | ----------- | ---------- | -| [Helm Tiller](https://docs.helm.sh) | 11.6+ | Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. | n/a | -| [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress) | 11.6+ | Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use [Auto DevOps](../../../topics/autodevops/index.md) or deploy your own web apps. | [stable/nginx-ingress](https://github.com/helm/charts/tree/master/stable/nginx-ingress) | -| [Cert-Manager](https://docs.cert-manager.io/en/latest/) | 11.6+ | Cert-Manager is a native Kubernetes certificate management controller that helps with issuing certificates. Installing Cert-Manager on your cluster will issue a certificate by [Let's Encrypt](https://letsencrypt.org/) and ensure that certificates are valid and up-to-date. | [stable/cert-manager](https://github.com/helm/charts/tree/master/stable/cert-manager) | -| [GitLab Runner](https://docs.gitlab.com/runner/) | 11.10+ | GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with [GitLab CI/CD](../../../ci/README.md), the open-source continuous integration service included with GitLab that coordinates the jobs. When installing the GitLab Runner via the applications, it will run in **privileged mode** by default. Make sure you read the [security implications](../../project/clusters/index.md#security-implications) before doing so. | [runner/gitlab-runner](https://gitlab.com/charts/gitlab-runner) | - -NOTE: **Note:** -Some [cluster -applications](../../project/clusters/index.md#installing-applications) -are installable only for a project-level cluster. Support for installing these -applications in a group-level cluster is planned for future releases. For updates, see: - -- Support installing [JupyterHub in group-level - clusters](https://gitlab.com/gitlab-org/gitlab-ce/issues/51989) -- Support installing [Prometheus in group-level - clusters](https://gitlab.com/gitlab-org/gitlab-ce/issues/51963) +GitLab can install and manage some applications in your group-level +cluster. For more information on installing, upgrading, uninstalling, +and troubleshooting applications for your group cluster, see +[Gitlab Managed Apps](../../clusters/applications.md). ## RBAC compatibility @@ -72,6 +52,29 @@ Add another cluster similar to the first one and make sure to [set an environment scope](#environment-scopes-premium) that will differentiate the new cluster from the rest. +## GitLab-managed clusters + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22011) in GitLab 11.5. +> Became [optional](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26565) in GitLab 11.11. + +NOTE: **Note:** +Only available when creating clusters. Existing clusters not managed by GitLab +cannot become GitLab-managed later. + +You can choose to allow GitLab to manage your cluster for you. If your cluster is +managed by GitLab, resources for your projects will be automatically created. See the +[Access controls](../../project/clusters/index.md#access-controls) section for details on which resources will +be created. + +If you choose to manage your own cluster, project-specific resources will not be created +automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you will +need to explicitly provide the `KUBE_NAMESPACE` [deployment variable](../../project/clusters/index.md#deployment-variables) +that will be used by your deployment jobs. + +NOTE: **Note:** +If you [install applications](#installing-applications) on your cluster, GitLab will create +the resources required to run these even if you have chosen to manage your own cluster. + ## Base domain > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24580) in GitLab 11.8. @@ -88,7 +91,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address. 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) +[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium) work. While evaluating which environment matches the environment scope of a @@ -146,3 +149,15 @@ The following features are not currently available for group-level clusters: 1. Terminals (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55487)). 1. Pod logs (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55488)). 1. Deployment boards (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55489)). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/contribution_analytics/img/group_stats_cal.png b/doc/user/group/contribution_analytics/img/group_stats_cal.png Binary files differnew file mode 100644 index 00000000000..0238c7bf088 --- /dev/null +++ b/doc/user/group/contribution_analytics/img/group_stats_cal.png diff --git a/doc/user/group/contribution_analytics/img/group_stats_graph.png b/doc/user/group/contribution_analytics/img/group_stats_graph.png Binary files differnew file mode 100644 index 00000000000..ccfd3782c6f --- /dev/null +++ b/doc/user/group/contribution_analytics/img/group_stats_graph.png diff --git a/doc/user/group/contribution_analytics/img/group_stats_table.png b/doc/user/group/contribution_analytics/img/group_stats_table.png Binary files differnew file mode 100644 index 00000000000..f1d1031fa18 --- /dev/null +++ b/doc/user/group/contribution_analytics/img/group_stats_table.png diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md new file mode 100644 index 00000000000..7e6cb24a51e --- /dev/null +++ b/doc/user/group/contribution_analytics/index.md @@ -0,0 +1,77 @@ +--- +type: reference +--- + +# Contribution Analytics **[STARTER]** + +> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. + +## Overview + +With Contribution Analytics you can get an overview of the following activity in your +group: + +- Issues +- Merge requests +- Push events + +To view the Contribution Analytics, go to your group's **Overview > Contribution Analytics** +page. + +## Use cases + +- Analyze your team's contributions over a period of time, and offer a bonus for the top +contributors. +- Identify opportunities for improvement with group members who may benefit from additional +support. + +## Using Contribution Analytics + +There are three main bar graphs that illustrate the number of contributions per group +member for the following: + +- Push events +- Merge requests +- Closed issues + +Hover over each bar to display the number of events for a specific group member. + + + +## Changing the period time + +You can choose from the following three periods: + +- Last week (default) +- Last month +- Last three months + +Select the desired period from the calendar dropdown. + + + +## Sorting by different factors + +Contributions per group member are also presented in tabular format. Click a column header to sort the table by that column: + +* Member name +* Number of pushed events +* Number of opened issues +* Number of closed issues +* Number of opened MRs +* Number of accepted MRs +* Number of total contributions + + + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 8e101407ac0..aa088d2fcdb 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -1,4 +1,8 @@ -# Custom group-level project templates **[PREMIUM ONLY]** +--- +type: reference +--- + +# Custom group-level project templates **[PREMIUM]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing) 11.6. @@ -24,3 +28,15 @@ Projects of nested subgroups of a selected template source cannot be used. Repository and database information that are copied over to each new project are identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/dependency_proxy/img/group_dependency_proxy.png b/doc/user/group/dependency_proxy/img/group_dependency_proxy.png Binary files differnew file mode 100644 index 00000000000..035aff0b6c4 --- /dev/null +++ b/doc/user/group/dependency_proxy/img/group_dependency_proxy.png diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md new file mode 100644 index 00000000000..4fc2d8e9509 --- /dev/null +++ b/doc/user/group/dependency_proxy/index.md @@ -0,0 +1,74 @@ +# Dependency Proxy **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. + +NOTE: **Note:** +This is the user guide. In order to use the dependency proxy, an administrator +must first [configure it](../../../administration/dependency_proxy.md). + +For many organizations, it is desirable to have a local proxy for frequently used +upstream images/packages. In the case of CI/CD, the proxy is responsible for +receiving a request and returning the upstream image from a registry, acting +as a pull-through cache. + +The dependency proxy is available in the group level. To access it, navigate to +a group's **Overview > Dependency Proxy**. + + + +## Supported dependency proxies + +NOTE: **Note:** +For a list of the upcoming additions to the proxies, visit the +[direction page](https://about.gitlab.com/direction/package/dependency_proxy/#top-vision-items). + +The following dependency proxies are supported. + +| Dependency proxy | GitLab version | +| ---------------- | -------------- | +| Docker | 11.11+ | + +## Using the Docker dependency proxy + +With the Docker dependency proxy, you can use GitLab as a source for a Docker image. +To get a Docker image into the dependency proxy: + +1. Find the proxy URL on your group's page under **Overview > Dependency Proxy**, + for example `gitlab.com/groupname/dependency_proxy/containers`. +1. Trigger GitLab to pull the Docker image you want (e.g., `alpine:latest` or + `linuxserver/nextcloud:latest`) and store it in the proxy storage by using + one of the following ways: + + - Manually pulling the Docker image: + + ```bash + docker pull gitlab.com/groupname/dependency_proxy/containers/alpine:latest + ``` + + - From a `Dockerfile`: + + ```bash + FROM gitlab.com/groupname/dependency_proxy/containers/alpine:latest + ``` + + - In [`.gitlab-ci.yml`](../../../ci/yaml/README.md#image): + + ```bash + image: gitlab.com/groupname/dependency_proxy/containers/alpine:latest + ``` + +GitLab will then pull the Docker image from Docker Hub and will cache the blobs +on the GitLab server. The next time you pull the same image, it will get the latest +information about the image from Docker Hub but will serve the existing blobs +from GitLab. + +The blobs are kept forever, and there is no hard limit on how much data can be +stored. + +## Limitations + +The following limitations apply: + +- Only public groups are supported (authentication is not supported yet). +- Only Docker Hub is supported. +- This feature requires Docker Hub being available. diff --git a/doc/user/group/epics/img/button_close_epic.png b/doc/user/group/epics/img/button_close_epic.png Binary files differnew file mode 100644 index 00000000000..aa1a889ea23 --- /dev/null +++ b/doc/user/group/epics/img/button_close_epic.png diff --git a/doc/user/group/epics/img/button_reopen_epic.png b/doc/user/group/epics/img/button_reopen_epic.png Binary files differnew file mode 100644 index 00000000000..7a953189270 --- /dev/null +++ b/doc/user/group/epics/img/button_reopen_epic.png diff --git a/doc/user/group/epics/img/child_epics_roadmap.png b/doc/user/group/epics/img/child_epics_roadmap.png Binary files differnew file mode 100644 index 00000000000..819fed58989 --- /dev/null +++ b/doc/user/group/epics/img/child_epics_roadmap.png diff --git a/doc/user/group/epics/img/containing_epic.png b/doc/user/group/epics/img/containing_epic.png Binary files differnew file mode 100644 index 00000000000..5ed693e6d6a --- /dev/null +++ b/doc/user/group/epics/img/containing_epic.png diff --git a/doc/user/group/epics/img/epic_view.png b/doc/user/group/epics/img/epic_view.png Binary files differnew file mode 100644 index 00000000000..dbda98e4351 --- /dev/null +++ b/doc/user/group/epics/img/epic_view.png diff --git a/doc/user/group/epics/img/epics_list_view.png b/doc/user/group/epics/img/epics_list_view.png Binary files differnew file mode 100644 index 00000000000..b30608d9d31 --- /dev/null +++ b/doc/user/group/epics/img/epics_list_view.png diff --git a/doc/user/group/epics/img/epics_search.png b/doc/user/group/epics/img/epics_search.png Binary files differnew file mode 100644 index 00000000000..96335527468 --- /dev/null +++ b/doc/user/group/epics/img/epics_search.png diff --git a/doc/user/group/epics/img/epics_sort.png b/doc/user/group/epics/img/epics_sort.png Binary files differnew file mode 100644 index 00000000000..b23c65fd0ef --- /dev/null +++ b/doc/user/group/epics/img/epics_sort.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md new file mode 100644 index 00000000000..2e4106f55e5 --- /dev/null +++ b/doc/user/group/epics/index.md @@ -0,0 +1,233 @@ +--- +type: reference, howto +--- + +# Epics **[ULTIMATE]** + +> Introduced in [GitLab Ultimate][ee] 10.2. + +Epics let you manage your portfolio of projects more efficiently and with less +effort by tracking groups of issues that share a theme, across projects and +milestones. + + + +## Use cases + +- Suppose your team is working on a large feature that involves multiple discussions throughout different issues created in distinct projects within a [Group](../index.md). With Epics, you can track all the related activities that together contribute to that single feature. +- Track when the work for the group of issues is targeted to begin, and when it is targeted to end. +- Discuss and collaborate on feature ideas and scope at a high-level. + +## Creating an epic + +A paginated list of epics is available in each group from where you can create +a new epic. The list of epics includes also epics from all subgroups of the +selected group. From your group page: + +1. Go to **Epics** +1. Click the **New epic** button at the top right +1. Enter a descriptive title and hit **Create epic** + +Once created, you will be taken to the view for that newly-created epic where +you can change its title, description, start date, and due date. + + + +## Adding an issue to an epic + +An epic contains a list of issues and an issue can be associated with at most +one epic. When on an epic, you can add its associated issues: + +1. Click the plus icon (<kbd>+</kbd>) under the epic description. +1. Paste the link of the issue (you can hit <kbd>Spacebar</kbd> to add more than + one issues at a time). +1. Click **Add**. + +Any issue belonging to a project in the epic's group or any of the epic's +subgroups are eligible to be added. To remove an issue from an epic, click +on the <kbd>x</kbd> button in the epic's issue list. + +NOTE: **Note:** +When you add an issue or an epic to an epic that's already associated with another epic, +the issue or the epic is automatically removed from the previous epic. + +## Multi-level child epics + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8333) in GitLab Ultimate 11.7. + +Much like adding issues to an epic, an epic can have multiple child epics with +the maximum depth being 5. To add a child epic: + +1. Click the plus icon (<kbd>+</kbd>) under the epic description. +1. Paste the link of the epic. +1. Click **Add**. + +Any epic that belongs to a group or subgroup of the parent epic's group is +eligible to be added. To remove a child epic from a parent epic, +click on the <kbd>x</kbd> button in the parent epic's epic list. + +## Start date and due date + +For each of the dates in the sidebar of an epic, you can choose to either: + +- Enter a fixed value. +- Inherit a dynamic value called "From milestones". + +If you select "From milestones" for the start date, GitLab will automatically set the +date to be earliest start date across all milestones that are currently assigned +to the issues that are attached to the epic. Similarly, if you select "From milestones" +for the due date, GitLab will set it to be the latest due date across all +milestones that are currently assigned to those issues. + +These are dynamic dates in that if milestones are re-assigned to the issues, if the +milestone dates change, or if issues are added or removed from the epic, then +the re-calculation will happen immediately to set a new dynamic date. + +## Roadmap in epics + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.10. + +If your epic contains one or more [child epics](#multi-level-child-epics) which +have a [start or due date](#start-date-and-due-date), then you can see a +[roadmap](../roadmap/index.md) view of the child epics under the parent epic itself. + + + +## Reordering issues and child epics + +Drag and drop to reorder issues and child epics. New issues and child epics added to an epic appear at the top of the list. + +## Deleting an epic + +NOTE: **Note:** +To delete an epic, you need to be an [Owner][permissions] of a group/subgroup. + +When inside a single epic view, click the **Delete** button to delete the epic. +A modal will pop-up to confirm your action. + +Deleting an epic releases all existing issues from their associated epic in the +system. + +## Closing and reopening epics + +### Using buttons + +Whenever you decide that there is no longer need for that epic, +close the epic using the close button: + + + +You can always reopen it using the reopen button. + + + +### Using quick actions + +You can close or reopen an epic using [Quick actions](../../project/quick_actions.md) + +## Navigating to an epic from an issue + +If an issue belongs to an epic, you can navigate to the containing epic with the +link in the issue sidebar. + + + +## Promoting an issue to an epic + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. + +If you have [permissions](../../permissions.md) to close an issue and create an +epic in the parent group, you can promote an issue to an epic with the `/promote` +[quick action](../../project/quick_actions.md#quick-actions-for-epics-ultimate). +Only issues from projects that are in groups can be promoted. + +When the quick action is executed: + +- An epic is created in the same group as the project of the issue. +- Subscribers of the issue are notified that the epic was created. + +The following issue metadata will be copied to the epic: + +- Title, description, activity/comment thread. +- Upvotes/downvotes. +- Participants. +- Group labels that the issue already has. + +## Searching for an epic from epics list page + +> Introduced in [GitLab Ultimate][ee] 10.5. + +You can search for an epic from the list of epics using filtered search bar (similar to +that of Issues and Merge requests) based on following parameters: + +- Title or description +- Author name / username +- Labels + + + +To search, go to the list of epics and click on the field **Search or filter results...**. +It will display a dropdown menu, from which you can add an author. You can also enter plain +text to search by epic title or description. When done, press <kbd>Enter</kbd> on your +keyboard to filter the list. + +You can also sort epics list by: + +- **Created date** +- **Last updated** +- **Start date** +- **Due date** + +Each option contains a button that can toggle the order between **ascending** and **descending**. The sort option and order will be persisted to be used wherever epics are browsed including the [roadmap](../roadmap/index.md). + + + +## Permissions + +If you have access to view an epic and have access to view an issue already +added to that epic, then you can view the issue in the epic issue list. + +If you have access to edit an epic and have access to edit an issue, then you +can add the issue to or remove it from the epic. + +Note that for a given group, the visibility of all projects must be the same as +the group, or less restrictive. That means if you have access to a group's epic, +then you already have access to its projects' issues. + +You may also consult the [group permissions table][permissions]. + +[ee]: https://about.gitlab.com/pricing/ +[permissions]: ../../permissions.md#group-members-permissions + +## Thread + +- Comments: collaborate on that epic by posting comments in its thread. +These text fields also fully support +[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). + +## Comment, or start a discussion + +Once you wrote your comment, you can either: + +- Click "Comment" and your comment will be published. +- Click "Start discussion": start a thread within that epic's thread to discuss specific points. + +## Award emoji + +- You can [award an emoji](../../award_emojis.md) to that epic or its comments. + +## Notifications + +- [Receive notifications](../../../workflow/notifications.md) for epic events. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/img/group_file_template_dropdown.png b/doc/user/group/img/group_file_template_dropdown.png Binary files differnew file mode 100644 index 00000000000..d9caae1a223 --- /dev/null +++ b/doc/user/group/img/group_file_template_dropdown.png diff --git a/doc/user/group/img/group_file_template_settings.png b/doc/user/group/img/group_file_template_settings.png Binary files differnew file mode 100644 index 00000000000..ca42f7726db --- /dev/null +++ b/doc/user/group/img/group_file_template_settings.png diff --git a/doc/user/group/img/member_lock.png b/doc/user/group/img/member_lock.png Binary files differnew file mode 100644 index 00000000000..3f1382e76c6 --- /dev/null +++ b/doc/user/group/img/member_lock.png diff --git a/doc/user/group/img/membership_lock.png b/doc/user/group/img/membership_lock.png Binary files differdeleted file mode 100644 index c9ad82c90f2..00000000000 --- a/doc/user/group/img/membership_lock.png +++ /dev/null diff --git a/doc/user/group/img/new_group_form.png b/doc/user/group/img/new_group_form.png Binary files differdeleted file mode 100644 index 1c4d3ec6ceb..00000000000 --- a/doc/user/group/img/new_group_form.png +++ /dev/null diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 74735886350..97d309caf7c 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,35 +1,51 @@ +--- +type: reference, howto +--- + # Groups -With GitLab Groups you can assemble related projects together -and grant members access to several projects at once. +With GitLab Groups, you can: + +- Assemble related projects together. +- Grant members access to several projects at once. + +For a video introduction to GitLab Groups, see [GitLab University: Repositories, Projects and Groups](https://www.youtube.com/watch?v=4TWfh1aKHHw). Groups can also be nested in [subgroups](subgroups/index.md). -Find your groups by expanding the left menu and clicking **Groups**: +Find your groups by clicking **Groups > Your Groups** in the top navigation.  -The Groups page displays all groups you are a member of, how many projects it holds, -how many members it has, the group visibility, and, if you have enough permissions, -a link to the group settings. By clicking the last button you can leave that group. +> The **Groups** dropdown in the top navigation was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/36234) in [GitLab 11.1](https://about.gitlab.com/2018/07/22/gitlab-11-1-released/#groups-dropdown-in-navigation). + +The **Groups** page displays: + +- All groups you are a member of, when **Your groups** is selected. +- A list of public groups, when **Explore public groups** is selected. + +Each group on the **Groups** page is listed with: + +- How many subgroups it has. +- How many projects it contains. +- How many members the group has, not including members inherited from parent groups. +- The group's visibility. +- A link to the group's settings, if you have sufficient permissions. +- A link to leave the group, if you are a member. ## Use cases -You can create groups for numerous reasons. To name a few: - -- Organize related projects under the same [namespace](#namespaces), add members to that - group and grant access to all their projects at once -- Create a group, include members of your team, and make it easier to - `@mention` all the team at once in issues and merge requests - - Create a group for your company members, and create [subgroups](subgroups/index.md) - for each individual team. Let's say you create a group called `company-team`, and among others, - you created subgroups in this group for each individual team `backend-team`, - `frontend-team`, and `production-team`: - 1. When you start a new implementation from an issue, you add a comment: +You can create groups for numerous reasons. To name a couple: + +- Grant access to multiple projects and multiple team members in fewer steps by organizing related projects under the same [namespace](#namespaces) and adding members to the top-level group. +- Make it easier to `@mention` all of your team at once in issues and merge requests by creating a group and including the appropriate members. + +For example, you could create a group for your company members, and create a [subgroup](subgroups/index.md) for each individual team. Let's say you create a group called `company-team`, and you create subgroups in this group for the individual teams `backend-team`, `frontend-team`, and `production-team`. + - When you start a new implementation from an issue, you add a comment: _"`@company-team`, let's do it! `@company-team/backend-team` you're good to go!"_ - 1. When your backend team needs help from frontend, they add a comment: + - When your backend team needs help from frontend, they add a comment: _"`@company-team/frontend-team` could you help us here please?"_ - 1. When the frontend team completes their implementation, they comment: + - When the frontend team completes their implementation, they comment: _"`@company-team/backend-team`, it's done! Let's ship it `@company-team/production-team`!"_ ## Namespaces @@ -44,7 +60,7 @@ For example, consider a user named Alex: 1. Alex creates an account on GitLab.com with the username `alex`; their profile will be accessed under `https://gitlab.example.com/alex` -1. Alex creates a group for their team with the groupname `alex-team`; +1. Alex creates a group for their team with the group name `alex-team`; the group and its projects will be accessed under `https://gitlab.example.com/alex-team` 1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`; this subgroup and its projects will be accessed under `https://gitlab.example.com/alex-team/marketing` @@ -57,8 +73,8 @@ By doing so: ## Issues and merge requests within a group -Issues and merge requests are part of projects. For a given group, view all the -[issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/index.md#merge-requests-per-group) across all the projects in that group, +Issues and merge requests are part of projects. For a given group, you can view all of the +[issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/index.md#merge-requests-per-group) across all projects in that group, together in a single list view. ## Create a new group @@ -66,13 +82,13 @@ together in a single list view. > For a list of words that are not allowed to be used as group names see the > [reserved names](../reserved_names.md). -You can create a group in GitLab from: +To create a new Group, either: -1. The Groups page: expand the left menu, click **Groups**, and click the green button **New group**: +- In the top menu, click **Groups** and then **Your Groups**, and click the green button **New group**.  -1. Elsewhere: expand the `plus` sign button on the top navbar and choose **New group**: +- Or, in the top menu, expand the `plus` sign and choose **New group**.  @@ -80,57 +96,60 @@ Add the following information:  -1. Set the **Group path** which will be the **namespace** under which your projects - will be hosted (path can contain only letters, digits, underscores, dashes - and dots; it cannot start with dashes or end in dot). -1. The **Group name** will populate with the path. Optionally, you can change - it. This is the name that will display in the group views. -1. Optionally, you can add a description so that others can briefly understand +1. The **Group name** will automatically populate the URL. Optionally, you can change it. + This is the name that displays in group views. + The name can contain only: + - Alphanumeric characters + - Underscores + - Dashes and dots + - Spaces +1. The **Group URL** is the namespace under which your projects will be hosted. + The URL can contain only: + - Alphanumeric characters + - Underscores + - Dashes and dots (it cannot start with dashes or end in a dot) +1. Optionally, you can add a brief description to tell others what this group is about. -1. Optionally, choose an avatar for your project. +1. Optionally, choose an avatar for your group. 1. Choose the [visibility level](../../public_access/public_access.md). +For more details on creating groups, watch the video [GitLab Namespaces (users, groups and subgroups)](https://youtu.be/r0sJgjR2f5A). + ## Add users to a group -Add members to a group by navigating to the group's dashboard, and clicking **Members**: +A benefit of putting multiple projects in one group is that you can +give a user to access to all projects in the group with one action. + +Add members to a group by navigating to the group's dashboard and clicking **Members**.  -Select the [permission level](../permissions.md#permissions) and add the new member. You can also set the expiring -date for that user, from which they will no longer have access to your group. - -One of the benefits of putting multiple projects in one group is that you can -give a user to access to all projects in the group with one action. +Select the [permission level](../permissions.md#permissions), and add the new member. You can also set the expiring date for that user; this is the date on which they will no longer have access to your group. -Consider we have a group with two projects: +Consider a group with two projects: -- On the **Group Members** page we can now add a new user to the group. -- Now because this user is a **Developer** member of the group, he automatically +- On the **Group Members** page, you can now add a new user to the group. +- Now, because this user is a **Developer** member of the group, they automatically gets **Developer** access to **all projects** within that group. -If necessary, you can increase the access level of an individual user for a specific project, -by adding them again as a new member to the project with the new permission levels. +To increase the access level of an existing user for a specific project, +add them again as a new member to the project with the desired permission level. ## Request access to a group -As a group owner you can enable or disable non members to request access to -your group. Go to the group settings and click on **Allow users to request access**. +As a group owner, you can enable or disable the ability for non members to request access to +your group. Go to the group settings, and click **Allow users to request access**. -As a user, you can request to be a member of a group. Go to the group you'd -like to be a member of, and click the **Request Access** button on the right +As a user, you can request to be a member of a group, if that setting is enabled. Go to the group for which you'd like to be a member, and click the **Request Access** button on the right side of your screen.  ---- - Group owners and maintainers will be notified of your request and will be able to approve or decline it on the members page.  ---- - If you change your mind before your request is approved, just click the **Withdraw Access Request** button. @@ -140,25 +159,27 @@ If you change your mind before your request is approved, just click the There are two different ways to add a new project to a group: -- Select a group and then click on the **New project** button. +- Select a group, and then click **New project**. You can then continue [creating your project](../../gitlab-basics/create-project.md).  - You can then continue on [creating a project](../../gitlab-basics/create-project.md). - - While you are creating a project, select a group namespace you've already created from the dropdown menu.  -### Default project creation level +### Default project-creation level + +> [Introduced][ee-2534] in [GitLab Premium][ee] 10.5. +> Brought to [GitLab Starter][ee] in 10.7. +> [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25975) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.10. -Group owners or administrators can allow users with the +Group owners and administrators can allow users with the Developer role to create projects under groups. -By default, [Developers and Maintainers](../permissions.md#group-members-permissions) can create projects under agroup, but this can be changed either within the group settings for a group, or -be set globally by a GitLab administrator in the Admin area -at **Settings > General > Visibility and access controls**. +By default, [Developers and Maintainers](../permissions.md#group-members-permissions) can create projects under a group. You can change this setting for a specific group within the group settings, or +you can set this option globally in the Admin area +at **Settings > General > Visibility and access controls** (you must be a GitLab administrator). Available settings are `No one`, `Maintainers`, or `Developers + Maintainers`. @@ -169,41 +190,69 @@ Learn how to [transfer a project into a group](../project/settings/index.md#tran ## Sharing a project with a group You can [share your projects with a group](../project/members/share_project_with_groups.md) -and give your group members access to the project all at once. +and give all group members access to the project at once. Alternatively, you can [lock the sharing with group feature](#share-with-group-lock). ## Manage group memberships via LDAP -In GitLab Enterprise Edition it is possible to manage GitLab group memberships using LDAP groups. +In GitLab Enterprise Edition, it is possible to manage GitLab group memberships using LDAP groups. See [the GitLab Enterprise Edition documentation](../../integration/ldap.md) for more information. +## Epics **[ULTIMATE]** + +> Introduced in [GitLab Ultimate][ee] 10.2. + +Epics let you manage your portfolio of projects more efficiently and with less +effort by tracking groups of issues that share a theme, across projects and +milestones. + +[Learn more about Epics.](epics/index.md) + +## Group Security Dashboard **[ULTIMATE]** + +Get an overview of the vulnerabilities of all the projects in a group and its subgroups. + +[Learn more about the Group Security Dashboard.](security_dashboard/index.md) + +## Insights **[ULTIMATE]** + +Configure the Insights that matter for your groups or projects, allowing users +to explore data such as: + +- Triage hygiene +- Issues created/closed per a given period +- Average time for merge requests to be merged +- Much more + +[Learn more about Insights](insights/index.md). + ## Transferring groups -From GitLab 10.5, groups can be transferred in the following ways: +From GitLab 10.5, you can transfer groups in the following ways: -- Top-level groups can be transferred to a group, converting them into subgroups. -- Subgroups can be transferred to a new parent group. -- Subgroups can be transferred out from a parent group, converting them into top-level groups. +- Transfer a subgroup to a new parent group. +- Convert a top-level group into a subgroup by transferring it to the desired group. +- Convert a subgroup into a top-level group by transferring it out of its current group. When transferring groups, note: - Changing a group's parent can have unintended side effects. See [Redirects when changing repository paths](../project/index.md#redirects-when-changing-repository-paths). - You can only transfer groups to groups you manage. -- You will need to update your local repositories to point to the new location. -- If the parent group's visibility is lower than the group's current visibility, visibility levels for subgroups and projects will be changed to match the new parent group's visibility. -- Only explicit group membership is transferred, not inherited membership. If the group's owners have only inherited membership, this would leave the group without an owner. In this case, the user transferring the group becomes the group's owner. +- You must update your local repositories to point to the new location. +- If the parent group's visibility is lower than the group's current visibility, visibility levels for subgroups and projects will change to match the new parent group's visibility. +- Only explicit group membership is transferred, not inherited membership. If the group's owners have only inherited membership, this leaves the group without an owner. In this case, the user transferring the group becomes the group's owner. ## Group settings -Once you have created a group, you can manage its settings by navigating to +After creating a group, you can manage its settings by navigating to the group's dashboard, and clicking **Settings**.  ### General settings -Besides giving you the option to edit any settings you've previously +In addition to editing any settings you previously set when [creating the group](#create-a-new-group), you can also access further configurations for your group. @@ -214,14 +263,14 @@ Changing a group's path can have unintended side effects. Read before proceeding. If you are vacating the path so it can be claimed by another group or user, -you may need to rename the group name as well since both names and paths must +you may need to rename the group, too, since both names and paths must be unique. To change your group path: 1. Navigate to your group's **Settings > General**. -1. Enter a new name under "Group path". -1. Hit **Save group**. +1. Enter a new name under **Group path**. +1. Click **Save group**. CAUTION: **Caution:** It is currently not possible to rename a namespace if it contains a @@ -237,20 +286,17 @@ username, you can create a new group and transfer projects to it. Add a security layer to your group by [enforcing two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforcing-2fa-for-all-users-in-a-group) -to all group members. +for all group members. #### Share with group lock Prevent projects in a group from [sharing -a project with another group](../project/members/share_project_with_groups.md). -This allows for tighter control over project access. +a project with another group](../project/members/share_project_with_groups.md) to enable tighter control over project access. -For example, consider you have two distinct teams (Group A and Group B) -working together in a project. -To inherit the group membership, you share the project between the +For example, let's say you have two distinct teams (Group A and Group B) working together in a project, and to inherit the group membership, you share the project between the two groups A and B. **Share with group lock** prevents any project within -the group from being shared with another group. By doing so, you -guarantee only the right group members have access to that projects. +the group from being shared with another group, +guaranteeing that only the right group members have access to those projects. To enable this feature, navigate to the group settings page. Select **Share with group lock** and **Save the group**. @@ -259,29 +305,88 @@ To enable this feature, navigate to the group settings page. Select #### Member Lock **[STARTER]** -With **Member Lock** it is possible to lock membership in project to the -level of members in group. +Member lock lets a group owner prevent any new project membership to all of the +projects within a group, allowing tighter control over project membership. + +For example, if you want to lock the group for an [Audit Event](../../administration/audit_events.md), +enable Member lock to guarantee that project membership cannot be modified during that audit. + +To enable this feature: + +1. Navigate to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section, and select **Member lock**. +1. Click **Save changes**. + + + +This will disable the option for all users who previously had permissions to +operate project memberships, so no new users can be added. Furthermore, any +request to add a new user to a project through API will not be possible. + +#### Group file templates **[PREMIUM]** -Learn more about [Member Lock](https://docs.gitlab.com/ee/user/group/index.html#member-lock). +Group file templates allow you to share a set of templates for common file +types with every project in a group. It is analogous to the +[instance template repository](../admin_area/settings/instance_template_repository.md) +feature, and the selected project should follow the same naming conventions as +are documented on that page. -#### Group-level file templates **[PREMIUM]** +You can only choose projects in the group as the template source. +This includes projects shared with the group, but it **excludes** projects in +subgroups or parent groups of the group being configured. -Group-level file templates allow you to share a set of templates for common file -types with every project in a group. +You can configure this feature for both subgroups and parent groups. A project +in a subgroup will have access to the templates for that subgroup, as well as +any parent groups. -Learn more about [Group-level file templates](https://docs.gitlab.com/ee/user/group/index.html#group-level-file-templates-premium). + + +To enable this feature, navigate to the group settings page, expand the +**Templates** section, choose a project to act as the template repository, and +**Save group**. + + #### Group-level project templates **[PREMIUM]** -Define project templates at a group-level by setting a group as a template source. +Define project templates at a group level by setting a group as the template source. [Learn more about group-level project templates](custom_project_templates.md). ### Advanced settings -- **Projects**: view all projects within that group, add members to each project, - access each project's settings, and remove any project from the same screen. -- **Webhooks**: configure [webhooks](../project/integrations/webhooks.md) to your group. -- **Kubernetes cluster integration**: connect your GitLab group with [Kubernetes clusters](clusters/index.md). -- **Audit Events**: view [Audit Events](https://docs.gitlab.com/ee/administration/audit_events.html#audit-events) +- **Projects**: View all projects within that group, add members to each project, + access each project's settings, and remove any project, all from the same screen. +- **Webhooks**: Configure [webhooks](../project/integrations/webhooks.md) for your group. +- **Kubernetes cluster integration**: Connect your GitLab group with [Kubernetes clusters](clusters/index.md). +- **Audit Events**: View [Audit Events](../../administration/audit_events.md) for the group. **[STARTER ONLY]** -- **Pipelines quota**: keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group. +- **Pipelines quota**: Keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group. + +## User contribution analysis **[STARTER]** + +With [GitLab Contribution Analytics](contribution_analytics/index.md), +you have an overview of the contributions (pushes, merge requests, +and issues) performed by your group members. + +## Issues analytics **[PREMIUM]** + +With [GitLab Issues Analytics](issues_analytics/index.md), you can see a bar chart of the number of issues created each month in your groups. + +## Dependency Proxy **[PREMIUM]** + +Use GitLab as a [dependency proxy](dependency_proxy/index.md) for upstream Docker images. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> + +[ee]: https://about.gitlab.com/pricing/ +[ee-2534]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2534 diff --git a/doc/user/group/insights/img/insights_example_stacked_bar_chart.png b/doc/user/group/insights/img/insights_example_stacked_bar_chart.png Binary files differnew file mode 100644 index 00000000000..791d0e4bcdf --- /dev/null +++ b/doc/user/group/insights/img/insights_example_stacked_bar_chart.png diff --git a/doc/user/group/insights/img/insights_group_configuration.png b/doc/user/group/insights/img/insights_group_configuration.png Binary files differnew file mode 100644 index 00000000000..0af0073e448 --- /dev/null +++ b/doc/user/group/insights/img/insights_group_configuration.png diff --git a/doc/user/group/insights/img/insights_sidebar_link.png b/doc/user/group/insights/img/insights_sidebar_link.png Binary files differnew file mode 100644 index 00000000000..64bbd1fc4d3 --- /dev/null +++ b/doc/user/group/insights/img/insights_sidebar_link.png diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md new file mode 100644 index 00000000000..1aba5d0986b --- /dev/null +++ b/doc/user/group/insights/index.md @@ -0,0 +1,58 @@ +--- +type: reference, howto +--- + +# Insights **[ULTIMATE]** + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9 behind the `insights` feature flag. +> **Generally Available** (GA) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. + +Configure the Insights that matter for your groups to explore data such as +triage hygiene, issues created/closed per a given period, average time for merge +requests to be merged and much more. + + + +## View your group's Insights + +You can access your group's Insights by clicking the **Overview > Insights** +link in the left sidebar: + + + +## Configure your Insights + +Navigate to your group's **Settings > General**, expand **Insights**, and choose +the project that holds your `.gitlab/insights.yml` configuration file: + + + +If no configuration was set, a [default configuration file]( +https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/fixtures/insights/default.yml) +will be used. + +See the [Project's Insights documentation](../../project/insights/index.md) for +more details about the `.gitlab/insights.yml` configuration file. + +## Permissions + +If you have access to view a group, then you have access to view their Insights. + +NOTE: **Note:** +Issues or merge requests that you don't have access to (because you don't have +access to the project they belong to, or because they are confidential) are +filtered out of the Insights charts. + +You may also consult the [group permissions table](../../permissions.md#group-members-permissions). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/issues_analytics/img/issues_created_per_month.png b/doc/user/group/issues_analytics/img/issues_created_per_month.png Binary files differnew file mode 100644 index 00000000000..96f0d36c917 --- /dev/null +++ b/doc/user/group/issues_analytics/img/issues_created_per_month.png diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md new file mode 100644 index 00000000000..46d5c1e2e09 --- /dev/null +++ b/doc/user/group/issues_analytics/index.md @@ -0,0 +1,43 @@ +--- +type: reference +--- + +# Issues Analytics **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. + +Issues Analytics is a bar graph which illustrates the number of issues created each month. +The default timespan is 13 months, which includes the current month, and the 12 months +prior. + +To access the chart, navigate to a group's sidebar and select **Issues > Analytics**. + +Hover over each bar to see the total number of issues. + +To narrow the scope of issues included in the graph, enter your criteria in the +**Search or filter results...** field. Criteria from the following list can be typed in or selected from a menu: + +- Author +- Assignee +- Milestone +- Label +- My reaction +- Weight + +You can change the total number of months displayed by setting a URL parameter. +For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15` +shows a total of 15 months for the chart in the GitLab.org group. + + + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/roadmap/img/epics_state_dropdown.png b/doc/user/group/roadmap/img/epics_state_dropdown.png Binary files differnew file mode 100644 index 00000000000..cbcc3658a54 --- /dev/null +++ b/doc/user/group/roadmap/img/epics_state_dropdown.png diff --git a/doc/user/group/roadmap/img/roadmap_timeline_months.png b/doc/user/group/roadmap/img/roadmap_timeline_months.png Binary files differnew file mode 100644 index 00000000000..5a046b21507 --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_timeline_months.png diff --git a/doc/user/group/roadmap/img/roadmap_timeline_quarters.png b/doc/user/group/roadmap/img/roadmap_timeline_quarters.png Binary files differnew file mode 100644 index 00000000000..56f428cb471 --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_timeline_quarters.png diff --git a/doc/user/group/roadmap/img/roadmap_timeline_weeks.png b/doc/user/group/roadmap/img/roadmap_timeline_weeks.png Binary files differnew file mode 100644 index 00000000000..bf4c1dc0284 --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_timeline_weeks.png diff --git a/doc/user/group/roadmap/img/roadmap_view.png b/doc/user/group/roadmap/img/roadmap_view.png Binary files differnew file mode 100644 index 00000000000..ff41a2e0441 --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_view.png diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md new file mode 100644 index 00000000000..683c715c8d5 --- /dev/null +++ b/doc/user/group/roadmap/index.md @@ -0,0 +1,87 @@ +--- +type: reference +--- + +# Roadmap **[ULTIMATE]** + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.5. + +An Epic within a group containing **Start date** and/or **Due date** +can be visualized in a form of a timeline (e.g. a Gantt chart). The Epics Roadmap page +shows such a visualization for all the epics which are under a group and/or its subgroups. + + + +A dropdown allows you to show only open or closed epics. By default, all epics are shown. + + + +Epics in the view can be sorted by: + +- **Created date** +- **Last updated** +- **Start date** +- **Due date** + +Each option contains a button that toggles the sort order between **ascending** and **descending**. The sort option and order will be persisted when browsing Epics, +including the [epics list view](../epics/index.md). + +Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). + +## Timeline duration + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.0. + +Roadmap supports the following date ranges: + +- Quarters +- Months (Default) +- Weeks + +### Quarters + + + +In _Quarters_ preset, roadmap shows epics which have start or due dates _falling within_ or +_going through_ **past quarter**, **current quarter** and **next 4 quarters**, where _today_ +is shown by the vertical red line in the timeline. The sub-headers underneath the quarter name on +the timeline header represent the month of the quarter. + +### Months + + + +In _Months_ preset, roadmap shows epics which have start or due dates _falling within_ or +_going through_ **past month**, **current month** and **next 5 months**, where _today_ +is shown by the vertical red line in the timeline. The sub-headers underneath the month name on +the timeline header represent the date on starting day (Sunday) of the week. This preset is +selected by default. + +### Weeks + + + +In _Weeks_ preset, roadmap shows epics which have start or due dates _falling within_ or +_going through_ **past week**, **current week** and **next 4 weeks**, where _today_ +is shown by the vertical red line in the timeline. The sub-headers underneath the week name on +the timeline header represent the days of the week. + +## Timeline bar for an epic + +The timeline bar indicates the approximate position of an epic based on its start +and due date. If an epic doesn't have a due date, the timeline bar fades +away towards the future. Similarly, if an epic doesn't have a start date, the +timeline bar becomes more visible as it approaches the epic's due date on the +timeline. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/saml_sso/img/group_saml_configuration_information.png b/doc/user/group/saml_sso/img/group_saml_configuration_information.png Binary files differnew file mode 100644 index 00000000000..98b83d0cb0f --- /dev/null +++ b/doc/user/group/saml_sso/img/group_saml_configuration_information.png diff --git a/doc/user/group/saml_sso/img/group_saml_settings.png b/doc/user/group/saml_sso/img/group_saml_settings.png Binary files differnew file mode 100644 index 00000000000..d95acb5075f --- /dev/null +++ b/doc/user/group/saml_sso/img/group_saml_settings.png diff --git a/doc/user/group/saml_sso/img/scim_advanced.png b/doc/user/group/saml_sso/img/scim_advanced.png Binary files differnew file mode 100644 index 00000000000..3b70e3fbe83 --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_advanced.png diff --git a/doc/user/group/saml_sso/img/scim_attribute_mapping.png b/doc/user/group/saml_sso/img/scim_attribute_mapping.png Binary files differnew file mode 100644 index 00000000000..c9f6b71f5b0 --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_attribute_mapping.png diff --git a/doc/user/group/saml_sso/img/scim_token.png b/doc/user/group/saml_sso/img/scim_token.png Binary files differnew file mode 100644 index 00000000000..7eb52bf6ea2 --- /dev/null +++ b/doc/user/group/saml_sso/img/scim_token.png diff --git a/doc/user/group/saml_sso/img/unlink_group_saml.png b/doc/user/group/saml_sso/img/unlink_group_saml.png Binary files differnew file mode 100644 index 00000000000..0561443b5f4 --- /dev/null +++ b/doc/user/group/saml_sso/img/unlink_group_saml.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md new file mode 100644 index 00000000000..fcfd638f185 --- /dev/null +++ b/doc/user/group/saml_sso/index.md @@ -0,0 +1,140 @@ +--- +type: reference, howto +--- + +# SAML SSO for GitLab.com Groups **[SILVER ONLY]** + +> Introduced in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.0. + +NOTE: **Note:** +This topic is for SAML on GitLab.com Silver tier and above. For SAML on self-managed GitLab instances, see [SAML OmniAuth Provider](../../../integration/saml.md). + +SAML on GitLab.com allows users to be automatically added to a group, and then allows those users to sign into GitLab.com. Users should already have an account on the GitLab instance, or can create one when logging in for the first time. + +User synchronization for GitLab.com is partially supported using [SCIM](scim_setup.md). + +NOTE: **Note:** +SAML SSO for GitLab.com groups does not sync users between providers without using SCIM. If a group is not using SCIM, group Owners will still need to manage user accounts (for example, removing users when necessary). + +## Configuring your Identity Provider + +1. Navigate to the group and click **Settings > SAML SSO**. +1. Configure your SAML server using the **Assertion consumer service URL** and **Identifier**. Alternatively GitLab provides [metadata XML configuration](#metadata-configuration). See [your identity provider's documentation](#providers) for more details. +1. Configure the SAML response to include a NameID that uniquely identifies each user. +1. Configure required assertions using the [table below](#assertions). +1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab). + + + +### SSO enforcement + +SSO enforcement was: + +- [Introduced in GitLab 11.8](https://gitlab.com/gitlab-org/gitlab-ee/issues/5291). +- [Improved upon in GitLab 11.11 with ongoing enforcement in the GitLab UI](https://gitlab.com/gitlab-org/gitlab-ee/issues/9255). + +With this option enabled, users must use your group's GitLab single sign on URL to be added to the group or be added via SCIM. Users cannot be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. + +We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab-ee/issues/9152) in the future. + +### NameID + +GitLab.com uses the SAML NameID to identify users. The NameID element: + +- Is a required field in the SAML response. +- Must be unique to each user. +- Must be a persistent value that will never change, such as a unique ID or username. Email could also be used as the NameID, but only if it can be guaranteed to never change. + +### Assertions + +| Field | Supported keys | +|-------|----------------| +| Email (required)| `email`, `mail` | +| Full Name | `name` | +| First Name | `first_name`, `firstname`, `firstName` | +| Last Name | `last_name`, `lastname`, `lastName` | + +## Metadata configuration + +GitLab provides metadata XML that can be used to configure your Identity Provider. + +1. Navigate to the group and click **Settings > SAML SSO**. +1. Copy the provided **GitLab metadata URL** +1. Follow your Identity Provider's documentation and paste the metadata URL when it is requested. + +## Configuring GitLab + +Once you've set up your identity provider to work with GitLab, you'll need to configure GitLab to use it for authentication: + +1. Navigate to the group's **Settings > SAML SSO**. +1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign on URL** field. +1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field. +1. Check the **Enable SAML authentication for this group** checkbox. +1. Click the **Save changes** button. + + + +## Providers + +| Provider | Documentation | +|----------|---------------| +| ADFS (Active Directory Federation Services) | [Create a Relying Party Trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) | +| Azure | [Configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/active-directory-saas-custom-apps) | +| Auth0 | [Auth0 as Identity Provider](https://auth0.com/docs/protocols/saml/saml-idp-generic) | +| G Suite | [Set up your own custom SAML application](https://support.google.com/a/answer/6087519?hl=en) | +| JumpCloud | [Single Sign On (SSO) with GitLab](https://support.jumpcloud.com/customer/en/portal/articles/2810701-single-sign-on-sso-with-gitlab) | +| Okta | [Setting up a SAML application in Okta](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta) | +| OneLogin | [Use the OneLogin SAML Test Connector](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) | +| Ping Identity | [Add and configure a new SAML application](https://docs.pingidentity.com/bundle/p1_enterpriseConfigSsoSaml_cas/page/enableAppWithoutURL.html) | + +## Linking SAML to your existing GitLab.com account + +To link SAML to your existing GitLab.com account: + +1. Sign in to your GitLab.com account. +1. Locate the SSO URL for the group you are signing in to. A group Admin can find this on the group's **Settings > SAML SSO** page. +1. Visit the SSO URL and click **Authorize**. +1. Enter your credentials on the Identity Provider if prompted. +1. You will be redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. + +## Signing in to GitLab.com with SAML + +1. Locate the SSO URL for the group you are signing in to. A group Admin can find this on a group's **Settings > SAML SSO** page. If configured, it might also be possible to sign in to GitLab starting from your Identity Provider. +1. Visit the SSO URL and click the **Sign in with Single Sign-On** button. +1. Enter your credentials on the Identity Provider if prompted. +1. You will be signed in to GitLab.com and redirected to the group. + +## Unlinking accounts + +Users can unlink SAML for a group from their profile page. This can be helpful if: + +- You no longer want a group to be able to sign you in to GitLab.com. +- Your SAML NameID has changed and so GitLab can no longer find your user. + +For example, to unlink the `MyOrg` account, the following **Disconnect** button will be available under **Profile > Accounts**: + + + +## Glossary + +| Term | Description | +|------|-------------| +| Identity Provider | The service which manages your user identities such as ADFS, Okta, Onelogin or Ping Identity. | +| Service Provider | SAML considers GitLab to be a service provider. | +| Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. | +| SSO | Single Sign On. | +| Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | +| Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | +| Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md new file mode 100644 index 00000000000..96cc523f4ec --- /dev/null +++ b/doc/user/group/saml_sso/scim_setup.md @@ -0,0 +1,122 @@ +--- +type: howto, reference +--- + +# SCIM provisioning using SAML SSO for Groups **[SILVER ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10. + +System for Cross-domain Identity Management (SCIM), is an open standard that enables the +automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of +that group is synchronized between GitLab and the identity provider. + +GitLab's [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). + +Currently, the following actions are available: + +- CREATE +- UPDATE +- DELETE (deprovisioning) + +The following identity providers are supported: + +- Azure + +## Requirements + +- [Group SSO](index.md) needs to be configured. +- The `scim_group` feature flag must be enabled: + + Run the following commands in a 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 + ``` + + To enable SCIM for a group named `group_name`: + + ```ruby + group = Group.find_by_full_path('group_name') + Feature.enable(:group_scim, group) + ``` + +### GitLab configuration + +Once [Single sign-on](index.md) has been configured, we can: + +1. Navigate to the group and click **Settings > SAML SSO**. +1. Click on the **Generate a SCIM token** button. +1. Save the token and URL so they can be used in the next step. + + + +## SCIM IdP configuration + +### Configuration on Azure + +In the [Single sign-on](index.md) configuration for the group, make sure +that the **Name identifier value** (NameID) points to a unique identifier, such +as the `user.objectid`. This will match the `extern_uid` used on GitLab. + +The GitLab app in Azure needs to be configured following +[Azure's SCIM setup](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#getting-started). + +Note the following: + +- The `Tenant URL` and `secret token` are the ones retrieved in the +[previous step](#gitlab-configuration). +- Should there be any problems with the availability of GitLab or similar +errors, the notification email set will get those. +- For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled. + +You can then test the connection clicking on `Test Connection`. + +### Synchronize Azure Active Directory users + +1. Click on `Synchronize Azure Active Directory Users to AppName`, to configure +the attribute mapping. +1. Select the unique identifier (in the example `objectId`) as the `id` and `externalId`, +and enable the `Create`, `Update`, and `Delete` actions. +1. Map the `userPricipalName` to `emails[type eq "work"].value` and `mailNickname` to +`userName`. + + Example configuration: + +  + +1. Click on **Show advanced options > Edit attribute list for AppName**. +1. Leave the `id` as the primary and only required field. + + NOTE: **Note:** + `username` should neither be primary nor required as we don't support + that field on GitLab SCIM yet. + +  + +1. Save all the screens and, in the **Provisioning** step, set +the `Provisioning Status` to `ON`. + + NOTE: **Note:** + You can control what is actually synced by selecting the `Scope`. For example, + `Sync only assigned users and groups` will only sync the users assigned to + the application (`Users and groups`), otherwise it will sync the whole Active Directory. + +Once enabled, the synchronization details and any errors will appear on the +bottom of the **Provisioning** screen, together with a link to the audit logs. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/security_dashboard/index.md b/doc/user/group/security_dashboard/index.md new file mode 100644 index 00000000000..c59198df081 --- /dev/null +++ b/doc/user/group/security_dashboard/index.md @@ -0,0 +1,5 @@ +--- +redirect_to: '../../application_security/security_dashboard/index.md' +--- + +This document was moved to [another location](../../application_security/security_dashboard/index.md). diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 4e81e28a45a..79ae94dd9ef 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,11 +1,17 @@ +--- +type: reference, howto, concepts +--- + # Subgroups NOTE: **Note:** [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2772) in GitLab 9.0. Not available when using MySQL as external database (support removed in GitLab 9.3 [due to performance reasons](https://gitlab.com/gitlab-org/gitlab-ce/issues/30472#note_27747600)). -With subgroups (aka nested groups or hierarchical groups) you can have -up to 20 levels of nested groups, which among other things can help you to: +Subgroups, also known as nested groups or hierarchical groups, allow you to have up to 20 +levels of groups. + +By using subgroups you can do the following: - **Separate internal / external organizations.** Since every group can have its own visibility level, you are able to host groups for different @@ -17,8 +23,9 @@ up to 20 levels of nested groups, which among other things can help you to: ## Database Requirements -Nested groups are only supported when you use PostgreSQL. Supporting nested -groups on MySQL in an efficient way is not possible due to MySQL's limitations. +Subgroups are only supported when you use PostgreSQL. Supporting subgroups on MySQL in an +efficient way is not possible due to MySQL's limitations. + See the following links for more information: - <https://gitlab.com/gitlab-org/gitlab-ce/issues/30472> @@ -37,7 +44,7 @@ only 1 parent group. It resembles a directory behavior or a nested items list: - Group 1.2.2.1 In a real world example, imagine maintaining a GNU/Linux distribution with the -first group being the name of the distro and subsequent groups split like: +first group being the name of the distribution, and subsequent groups split as follows: - Organization Group - GNU/Linux distro - Category Subgroup - Packages @@ -69,22 +76,22 @@ Another example of GitLab as a company would be the following: --- -The maximum nested groups a group can have, including the first one in the +The maximum subgroups a group can have, including the first one in the hierarchy, is 21. -Things like transferring or importing a project inside nested groups, work like +Actions such as transferring or importing a project inside subgroups, work like when performing these actions the traditional way with the `group/project` structure. ## Creating a subgroup NOTE: **Note:** -You need to be an Owner of a group in order to be able to create a subgroup. For +You must be an Owner of a group to create a subgroup. For more information check the [permissions table](../../permissions.md#group-members-permissions). For a list of words that are not allowed to be used as group names see the [reserved names](../../reserved_names.md). Users can always create subgroups if they are explicitly added as an Owner to -a parent group even if group creation is disabled by an administrator in their +a parent group, even if group creation is disabled by an administrator in their settings. To create a subgroup: @@ -111,7 +118,7 @@ When you add a member to a subgroup, they inherit the membership and permission level from the parent group. This model allows access to nested groups if you have membership in one of its parents. -The group permissions for a member can be changed only by Owners and only on +The group permissions for a member can be changed only by Owners, and only on the **Members** page of the group the member was added. You can tell if a member has inherited the permissions from a parent group by @@ -119,24 +126,24 @@ looking at the group's **Members** page.  -From the image above, we can deduct the following things: +From the image above, we can deduce the following things: -- There are 5 members that have access to the group `four` +- There are 5 members that have access to the group `four`. - User0 is a Reporter and has inherited their permissions from group `one` - which is above the hierarchy of group `four` + which is above the hierarchy of group `four`. - User1 is a Developer and has inherited their permissions from group - `one/two` which is above the hierarchy of group `four` + `one/two` which is above the hierarchy of group `four`. - User2 is a Developer and has inherited their permissions from group - `one/two/three` which is above the hierarchy of group `four` + `one/two/three` which is above the hierarchy of group `four`. - For User3 there is no indication of a parent group, therefore they belong to - group `four`, the one we're inspecting + group `four`, the one we're inspecting. - Administrator is the Owner and member of **all** subgroups and for that reason, - same as User3, there is no indication of an ancestor group + as with User3, there is no indication of an ancestor group. ### Overriding the ancestor group membership NOTE: **Note:** -You need to be an Owner of a group in order to be able to add members to it. +You must be an Owner of a group to be able to add members to it. NOTE: **Note:** A user's permissions in a subgroup cannot be lower than in any of its ancestor groups. @@ -154,7 +161,7 @@ the permissions will fallback to those of the ancestor group. ## Mentioning subgroups Mentioning groups (`@group`) in issues, commits and merge requests, would -notify all members of that group. Now with subgroups, there is a more granular +notify all members of that group. Now with subgroups, there is more granular support if you want to split your group's structure. Mentioning works as before and you can choose the group of people to be notified. @@ -179,3 +186,15 @@ Here's a list of what you can't do with subgroups: [permissions]: ../../permissions.md#group-members-permissions [reserved]: ../../reserved_names.md [issue]: https://gitlab.com/gitlab-org/gitlab-ce/issues/30472#note_27747600 + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> |
