diff options
Diffstat (limited to 'doc/user/group')
40 files changed, 679 insertions, 12 deletions
diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 0f71587830f..ae09453ce52 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -111,7 +111,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](https://docs.gitlab.com/ee/ci/variables/#limiting-environment-scopes-of-environment-variables-premium) work. While evaluating which environment matches the environment scope of a 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..bc88eff9ed2 --- /dev/null +++ b/doc/user/group/contribution_analytics/index.md @@ -0,0 +1,55 @@ +# Contribution Analytics **[STARTER]** + +>**Note:** +Introduced in [GitLab Starter][ee] 8.3. + +Track your team members' activity across your organization. + +## Overview + +With Contribution Analytics you can get an overview of the activity of +issues, merge requests, and push events of your organization and its members. + +The analytics page is located at **Group > Contribution Analytics** +under the URL `/groups/<groupname>/analytics`. + +## 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 are deducted from the number of +contributions per group member. These contributions include push events, merge +requests and closed issues. Hovering on each bar you can see the number of +events for a specific member. + + + +## Changing the period time + +There are three periods you can choose from, 'Last week', 'Last month' and +'Last three months'. The default is 'Last week'. + +You can choose which period to display by using the dropdown calendar menu in +the upper right corner. + + + +## Sorting by different factors + +Apart from the bar graphs you can also see the contributions per group member +which are depicted in a table that can be sorted by: + +* 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 + + + +[ee]: https://about.gitlab.com/pricing/ 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..6035f0c7326 --- /dev/null +++ b/doc/user/group/epics/index.md @@ -0,0 +1,217 @@ +# 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. 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/group_issue_board.png b/doc/user/group/img/group_issue_board.png Binary files differnew file mode 100644 index 00000000000..a0da74a320f --- /dev/null +++ b/doc/user/group/img/group_issue_board.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/index.md b/doc/user/group/index.md index 2d887673fd6..06564fd6cd1 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -5,10 +5,12 @@ and grant members access to several projects at once. 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** in the top navigation.  +> The groups dropdown in the top navigation was [introduced][ce-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, 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. @@ -44,7 +46,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` @@ -160,6 +162,10 @@ There are two different ways to add a new project to a group: ### 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 Developer role to create projects under groups. @@ -185,6 +191,32 @@ Alternatively, you can [lock the sharing with group feature](#share-with-group-l 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]** + +> Introduced in [GitLab Ultimate][ee] 11.9 behind the `insights` feature flag. + +Configure the Insights that matter for your groups or projects 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. + +[Learn more about Insights](insights/index.md). + ## Transferring groups From GitLab 10.5, groups can be transferred in the following ways: @@ -257,7 +289,7 @@ working together in a project. To inherit the group membership, you share the project between the two groups A and B. **Share with group lock** prevents any project within the group from being shared with another group. By doing so, you -guarantee only the right group members have access to that projects. +guarantee 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**. @@ -266,17 +298,50 @@ 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. +With Member lock, it is possible to lock membership in a project to the +level of members in the group. + +Member lock lets a group owner lock down any new project membership to all the +projects within the group, allowing tighter control over project membership. -Learn more about [Member Lock](https://docs.gitlab.com/ee/user/group/index.html#member-lock). +For instance, if you want to lock the group for an [Audit Event](https://docs.gitlab.com/ee/administration/audit_events.html), +you enable Member lock to guarantee that membership of a project cannot be modified during that audit. -#### Group-level file templates **[PREMIUM]** +To enable this feature: -Group-level file templates allow you to share a set of templates for common file -types with every project in a group. +1. Navigate to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section and select **Member lock**. +1. Click the **Save changes** button. -Learn more about [Group-level file templates](https://docs.gitlab.com/ee/user/group/index.html#group-level-file-templates-premium). + + +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]** + +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](https://docs.gitlab.com/ee/user/admin_area/settings/instance_template_repository.html) +feature, and the selected project should follow the same naming conventions as +are documented on that page. + +Only projects that are in the group may be chosen as the source of templates. +This includes projects shared with the group, but **excludes** projects in +subgroups or parent groups of the group being configured. + +This feature may be configured for subgroups as well as parent groups. A project +in a subgroup will have access to the templates for that subgroup, as well as +any parent groups. + + + +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]** @@ -289,6 +354,19 @@ Define project templates at a group-level by setting a group as a template sourc 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) +- **Audit Events**: view [Audit Events](https://docs.gitlab.com/ee/administration/audit_events.html) for the group. **[STARTER ONLY]** - **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), in groups, you can see a bar chart of the number of issues created each month. + +[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/index.md b/doc/user/group/insights/index.md new file mode 100644 index 00000000000..5283d8da77d --- /dev/null +++ b/doc/user/group/insights/index.md @@ -0,0 +1,39 @@ +# Insights **[ULTIMATE]** + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9 behind the `insights` feature flag. + +CAUTION: **Beta:** +Insights is considered beta, and is not ready for production use. +Follow [gitlab-org&725](https://gitlab.com/groups/gitlab-org/-/epics/725) for +updates. + +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. + + + +## 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/ee/fixtures/insights/default.yml) +will be used. + +See the [Project's Insights documentation](https://docs.gitlab.com/ee/user/project/insights/index.html) 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). 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..cf53d7423a6 --- /dev/null +++ b/doc/user/group/issues_analytics/index.md @@ -0,0 +1,16 @@ +# Issues Analytics **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. + +GitLab by default displays a bar chart of the number of issues created each month, for the +current month, and 12 months prior, for a total of 13 months. + +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` +would show a total of 15 months for the chart in the GitLab.org group. + +The **Search or filter results...** field can be used for filtering the issues by any attribute. For example, labels, assignee, milestone, and author. + +To access the chart, navigate to a group's sidebar and select **Issues > Analytics**. + + 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..310c4bb88d0 --- /dev/null +++ b/doc/user/group/roadmap/index.md @@ -0,0 +1,64 @@ +# 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 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 [epics list view](../epics/index.md). + +Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). + +## Timeline duration + +Starting with [GitLab Ultimate][ee] 11.0, Roadmap supports three different date ranges; Quarters, Months (Default) and 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. 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..ee3137d032e --- /dev/null +++ b/doc/user/group/saml_sso/index.md @@ -0,0 +1,91 @@ +# 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). + +Currently SAML on GitLab.com can be used to automatically add users to a group, and does not yet sign users 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 groups is used only as a convenient way to add users and 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, such as 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 **Issuer**. 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). + + + +NOTE: **Note:** +Partial SSO enforcement was introduced in [11.8](https://gitlab.com/gitlab-org/gitlab-ee/issues/5291). 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 can no longer be added manually. After a user has been added to the group, GitLab does not continue to enforce the use of SSO, but we'll [add a persistent check](https://gitlab.com/gitlab-org/gitlab-ee/issues/9255) in a later version. + +### 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 | Notes | +|-|----------------|-------------| +| Email | `email`, `mail` | (required) | +| Full Name | `name` | | +| First Name | `first_name`, `firstname`, `firstName` | | +| Last Name | `last_name`, `lastname`, `lastName` | | + +## 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) | + +## 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. | 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..ec27ec3e336 --- /dev/null +++ b/doc/user/group/saml_sso/scim_setup.md @@ -0,0 +1,102 @@ +# 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. + +GitLab's [SCIM API](https://docs.gitlab.com/ee/api/scim.html) 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. diff --git a/doc/user/group/security_dashboard/index.md b/doc/user/group/security_dashboard/index.md new file mode 100644 index 00000000000..43e910b29fe --- /dev/null +++ b/doc/user/group/security_dashboard/index.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). |
