diff --git a/doc/api/events.md b/doc/api/events.md index 265fc0e5fd2..3f032c72870 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ### Actions -See [User contribution events](../user/index.md#user-contribution-events) for available types for the `action` parameter. +See [User contribution events](../user/profile/index.md#user-contribution-events) for available types for the `action` parameter. These options are in lowercase. ### Target Types diff --git a/doc/topics/use_gitlab.md b/doc/topics/use_gitlab.md index 59a933b1441..6c6c5f71fc2 100644 --- a/doc/topics/use_gitlab.md +++ b/doc/topics/use_gitlab.md @@ -1,21 +1,11 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../user/index.md' +remove_date: '2022-06-17' --- -# Use GitLab **(FREE)** +This document was moved to [another location](../user/index.md). -Get to know the GitLab end-to-end workflow. Configure permissions, -organize your work, create and secure your application, and analyze its performance. Report on team productivity throughout the process. - -- [Set up your organization](set_up_organization.md) -- [Organize work with projects](../user/project/index.md) -- [Plan and track work](plan_and_track.md) -- [Build your application](build_your_application.md) -- [Secure your application](../user/application_security/index.md) -- [Deploy and release your application](release_your_application.md) -- [Monitor application performance](../operations/index.md) -- [Monitor runner performance](https://docs.gitlab.com/runner/monitoring/index.html) -- [Manage your infrastructure](../user/infrastructure/index.md) -- [Analyze GitLab usage](../user/analytics/index.md) + + + + diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 3b866c4a1b0..cd2d5c190a1 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) in GitLab 12.2 for subgroups. -With Contribution Analytics, you can get an overview of the [contribution events](../../index.md#user-contribution-events) in your +With Contribution Analytics, you can get an overview of the [contribution events](../../profile/index.md#user-contribution-events) in your group. - Analyze your team's contributions over a period of time. diff --git a/doc/user/index.md b/doc/user/index.md index 4ce46c5b46f..af106b85ce9 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -2,253 +2,20 @@ stage: none group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, index -description: 'Read through the GitLab User documentation to learn how to use, configure, and customize GitLab and GitLab.com to your own needs.' --- -# User Docs **(FREE)** - -Welcome to GitLab! We're glad to have you here! - -As a GitLab user you have access to all the features -your [subscription](https://about.gitlab.com/pricing/) -includes, except [GitLab administrator](../administration/index.md) -settings, unless you have administrator privileges to install, configure, -and upgrade your GitLab instance. - -Administrator privileges for [GitLab.com](https://gitlab.com/) are restricted to the GitLab team. - -For more information on configuring GitLab self-managed instances, see the [Administrator documentation](../administration/index.md). - -## Overview - -GitLab is a fully integrated software development platform that enables your team to be transparent, fast, effective, and cohesive from discussion on a new idea to production, all on the same platform. - -For more information, see [All GitLab Features](https://about.gitlab.com/features/). - -### Concepts - -To get familiar with the concepts needed to develop code on GitLab, read the following articles: - -- [Demo: Mastering Code Review With GitLab](https://about.gitlab.com/blog/2017/03/17/demo-mastering-code-review-with-gitlab/). -- [What is GitLab Flow?](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/). -- [Tutorial: It's all connected in GitLab](https://about.gitlab.com/blog/2016/03/08/gitlab-tutorial-its-all-connected/): an overview on code collaboration with GitLab. -- [Trends in Version Control Land: Microservices](https://about.gitlab.com/blog/2016/08/16/trends-in-version-control-land-microservices/). -- [Trends in Version Control Land: Innersourcing](https://about.gitlab.com/topics/version-control/what-is-innersource/). - -## Use cases - -GitLab is a Git-based platform that integrates a great number of essential tools for software development and deployment, and project management: - -- Hosting code in repositories with version control. -- Tracking proposals for new implementations, bug reports, and feedback with a - fully featured [Issue tracker](project/issues/index.md). -- Organizing and prioritizing with [issue boards](project/issue_board.md). -- Reviewing code in [merge requests](project/merge_requests/index.md) with live-preview changes per - branch with [Review Apps](../ci/review_apps/index.md). -- Building, testing, and deploying with built-in [Continuous Integration](../ci/index.md). -- View the current health and status of each CI environment running on Kubernetes with [deploy boards](project/deploy_boards.md). -- Leverage continuous delivery method with [Canary Deployments](project/canary_deployments.md). -- Deploying personal and professional static websites with [GitLab Pages](project/pages/index.md). -- Integrating with Docker by using [GitLab Container Registry](packages/container_registry/index.md). -- Tracking the development lifecycle by using [GitLab Value Stream Analytics](analytics/value_stream_analytics.md). -- Provide support with [Service Desk](project/service_desk.md). -- [Export issues as CSV](project/issues/csv_export.md). - -With GitLab Enterprise Edition, you can also: - -- Improve collaboration with: - - [Merge request approvals](project/merge_requests/approvals/index.md). - - [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md). - - [Multiple issue boards](project/issue_board.md#multiple-issue-boards). -- Create formal relationships between issues with [linked issues](project/issues/related_issues.md). -- Use [Burndown Charts](project/milestones/burndown_and_burnup_charts.md) to track progress during a sprint or while working on a new version of their software. -- Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Search](search/advanced_search.md) for faster, more advanced code search across your entire GitLab instance. -- [Authenticate users with Kerberos](../integration/kerberos.md). -- [Mirror a repository](project/repository/mirror/index.md) from elsewhere on your local server. -- View your entire CI/CD pipeline involving more than one project with [Multiple-Project Pipelines](../ci/pipelines/multi_project_pipelines.md). -- [Lock files](project/file_lock.md) to prevent conflicts. -- Scan your code for vulnerabilities and [display them in merge requests](application_security/sast/index.md). - -You can also [integrate](project/integrations/overview.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, Trello, Slack, Bamboo CI, Jira, and a lot more. - -## User types - -There are several types of users in GitLab: - -- Regular users. -- [Internal users](../development/internal_users.md) often referred to as bot or system users. -- [Auditor](permissions.md#auditor-users) with read access to self-managed instances. -- [GitLab Administrator](../administration/index.md) with full access to - self-managed instances including settings and the [Admin Area](admin_area/index.md). - -Each user can be a member in a [group](group/index.md). - -See the [permissions page](permissions.md) for details on how each user type is used. - -## User activity - -GitLab tracks user contribution activity. -You can follow or unfollow other users from their [user profiles](profile/index.md#access-your-user-profile). -To view a user's activity in a top-level Activity view: - -1. From a user's profile, select **Follow**. -1. In the GitLab menu, select **Activity**. -1. Select the **Followed users** tab. - -### User contribution events - -Each of these contribution events is tracked: - -- `approved` - - Merge request -- `closed` - - [Epic](group/epics/index.md) - - Issue - - Merge request - - Milestone -- `commented` on any `Noteable` record. - - Alert - - Commit - - Design - - Issue - - Merge request - - Snippet -- `created` - - Design - - [Epic](group/epics/index.md) - - Issue - - Merge request - - Milestone - - Project - - Wiki page -- `destroyed` - - Design - - Milestone - - Wiki page -- `expired` - - Project membership -- `joined` - - Project membership -- `left` - - Project membership -- `merged` - - Merge request -- `pushed` commits to (or deleted commits from) a repository, individually or in bulk. - - Project -- `reopened` - - [Epic](group/epics/index.md) - - Issue - - Merge request - - Milestone -- `updated` - - Design - - Wiki page - -## Projects - -In GitLab, you can create [projects](project/index.md) to host -your code, track issues, collaborate on code, and continuously -build, test, and deploy your app with built-in GitLab CI/CD. Or, you can do -it all at once, from one single project. - -- [Repositories](project/repository/index.md): Host your codebase in - repositories with version control and as part of a fully integrated platform. -- [Issues](project/issues/index.md): Explore the best of GitLab Issues' features. -- [Merge requests](project/merge_requests/index.md): Collaborate on code, - reviews, live preview changes per branch, and request approvals with merge requests. -- [Milestones](project/milestones/index.md): Work on multiple issues and merge - requests towards the same target date with Milestones. - -## Account - -There is a lot you can customize and configure to enjoy the best of GitLab. - -- [Settings](profile/index.md): Manage your user settings to change your personal information, - personal access tokens, authorized applications, etc. -- [Authentication](../topics/authentication/index.md): Read through the authentication - methods available in GitLab. -- [Permissions](permissions.md): Learn the different set of permissions levels for each - user type (guest, reporter, developer, maintainer, owner). -- [Feature highlight](feature_highlight.md): Learn more about the little blue dots - around the app that explain certain features. -- [Abuse reports](report_abuse.md): Report abuse from users to GitLab administrators. - -## Groups - -With GitLab [Groups](group/index.md) you can assemble related projects together -and grant members access to several projects at once. - -Groups can also be nested in [subgroups](group/subgroups/index.md). - -## Discussions - -In GitLab, you can comment and mention collaborators in issues, -merge requests, code snippets, and commits. - -When performing inline reviews to implementations -to your codebase through merge requests you can -gather feedback through [resolvable threads](discussions/index.md#resolve-a-thread). - -### GitLab Flavored Markdown (GFM) - -Read through the [GFM documentation](markdown.md) to learn how to apply -the best of GitLab Flavored Markdown in your threads, comments, -issues and merge requests descriptions, and everywhere else GFM is -supported. - -## To-Do List - -Never forget to reply to your collaborators. [GitLab To-Do List](todos.md) -is a tool for working faster and more effectively with your team, -by listing all user or group mentions, as well as issues and merge -requests you're assigned to. - -## Search - -[Search and filter](search/index.md) through groups, projects, issues, merge requests, files, code, and more. - -## Snippets - -[Snippets](snippets.md) are code blocks that you want to store in GitLab, from which -you have quick access to. You can also gather feedback on them through [Discussions](#discussions). - -## GitLab CI/CD - -Use built-in [GitLab CI/CD](../ci/index.md) to test, build, and deploy your applications -directly from GitLab. No third-party integrations needed. - -## Features behind feature flags - -Understand what [features behind feature flags](feature_flags.md) mean. - -## Keyboard shortcuts - -There are many [keyboard shortcuts](shortcuts.md) in GitLab to help you navigate between -pages and accomplish tasks faster. - -## Integrations - -[Integrate GitLab](../integration/index.md) with your preferred tool, such as Trello, Jira, etc. - -## Webhooks - -Configure [webhooks](project/integrations/webhooks.md) to listen for -specific events like pushes, issues or merge requests. GitLab sends a -POST request with data to the webhook URL. - -## API - -Automate GitLab via [API](../api/index.md). - -## Git and GitLab - -Learn what is [Git](../topics/git/index.md) and its best practices. - -## Instance-level analytics - -See [various statistics](admin_area/analytics/index.md) of your GitLab instance. - -## Operations Dashboard - -See [Operations Dashboard](operations_dashboard/index.md) for a summary of each project's operational health. +# Use GitLab **(FREE)** + +Get to know the GitLab end-to-end workflow. Configure permissions, +organize your work, create and secure your application, and analyze its performance. Report on team productivity throughout the process. + +- [Set up your organization](../topics/set_up_organization.md) +- [Organize work with projects](../user/project/index.md) +- [Plan and track work](../topics/plan_and_track.md) +- [Build your application](../topics/build_your_application.md) +- [Secure your application](../user/application_security/index.md) +- [Deploy and release your application](../topics/release_your_application.md) +- [Monitor application performance](../operations/index.md) +- [Monitor runner performance](https://docs.gitlab.com/runner/monitoring/index.html) +- [Manage your infrastructure](../user/infrastructure/index.md) +- [Analyze GitLab usage](../user/analytics/index.md) diff --git a/doc/user/markdown.md b/doc/user/markdown.md index c81fdc275d9..5d7c480143a 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -819,7 +819,8 @@ Regardless of the tag names, the relative order of the reference tags determines numbering. 
A footnote reference tag looks like this: [^1]
@@ -926,7 +927,8 @@ ___
 Examples:
 
 
 
 
Inline-style (hover to see title text):
@@ -1192,17 +1194,18 @@ A new line due to the previous backslash.
 You can create links two ways: inline-style and reference-style. For example:
 
 
 
 
- This line shows an [inline-style link](https://www.google.com)
-- This line shows a [link to a repository file in the same directory](index.md)
-- This line shows a [relative link to a readme one directory higher](../index.md)
+- This line shows a [link to a repository file in the same directory](permissions.md)
+- This line shows a [relative link to a file one directory higher](../index.md)
 - This line shows a [link that also has title text](https://www.google.com "This link takes you to Google!")
 
 Using header ID anchors:
 
-- This line links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview)
+- This line links to [a section on a different Markdown page, using a "#" and the header ID](permissions.md#project-features-permissions)
 - This line links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links)
 
 Using references:
@@ -1219,13 +1222,13 @@ Some text to show that the reference links can follow later.
 

 
 - This line shows an [inline-style link](https://www.google.com)
-- This line shows a [link to a repository file in the same directory](index.md)
-- This line shows a [relative link to a README one directory higher](../index.md)
+- This line shows a [link to a repository file in the same directory](permissions.md)
+- This line shows a [relative link to a file one directory higher](../index.md)
 - This line shows a [link that also has title text](https://www.google.com "This link takes you to Google!")
 
 Using header ID anchors:
 
-- This line links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview)
+- This line links to [a section on a different Markdown page, using a "#" and the header ID](permissions.md#project-features-permissions)
 - This line links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links)
 
 Using references:
diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md
index f201e04183c..17b1992353f 100644
--- a/doc/user/profile/index.md
+++ b/doc/user/profile/index.md
@@ -150,7 +150,7 @@ To add links to other accounts:
 
 ## Show private contributions on your user profile page
 
-In the user contribution calendar graph and recent activity list, you can see your [contribution actions](../index.md#user-contribution-events) to private projects.
+In the user contribution calendar graph and recent activity list, you can see your [contribution actions](#user-contribution-events) to private projects.
 
 To show private contributions:
 
@@ -322,6 +322,65 @@ and configure it on your local machine by using the following command:
 git config --global user.email 
 ```
 
+## User activity
+
+GitLab tracks user contribution activity.
+You can follow or unfollow other users from their [user profiles](#access-your-user-profile).
+To view a user's activity in a top-level Activity view:
+
+1. From a user's profile, select **Follow**.
+1. In the GitLab menu, select **Activity**.
+1. Select the **Followed users** tab.
+
+### User contribution events
+
+Each of these contribution events is tracked:
+
+- `approved`
+  - Merge request
+- `closed`
+  - [Epic](../group/epics/index.md)
+  - Issue
+  - Merge request
+  - Milestone
+- `commented` on any `Noteable` record.
+  - Alert
+  - Commit
+  - Design
+  - Issue
+  - Merge request
+  - Snippet
+- `created`
+  - Design
+  - [Epic](../group/epics/index.md)
+  - Issue
+  - Merge request
+  - Milestone
+  - Project
+  - Wiki page
+- `destroyed`
+  - Design
+  - Milestone
+  - Wiki page
+- `expired`
+  - Project membership
+- `joined`
+  - Project membership
+- `left`
+  - Project membership
+- `merged`
+  - Merge request
+- `pushed` commits to (or deleted commits from) a repository, individually or in bulk.
+  - Project
+- `reopened`
+  - [Epic](../group/epics/index.md)
+  - Issue
+  - Merge request
+  - Milestone
+- `updated`
+  - Design
+  - Wiki page
+
 ## Troubleshooting
 
 ### Why do I keep getting signed out?
diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md
index 2cb62b8924e..c91d59cc783 100644
--- a/doc/user/project/integrations/overview.md
+++ b/doc/user/project/integrations/overview.md
@@ -89,7 +89,7 @@ By default, the SSL certificate for outgoing HTTP requests is verified based on
 an internal list of Certificate Authorities. This means the certificate cannot
 be self-signed.
 
-You can turn off SSL verification in the configuration settings for [webhooks](webhooks.md#configure-a-webhook)
+You can turn off SSL verification in the configuration settings for [webhooks](webhooks.md#configure-a-webhook-in-gitlab)
 and some integrations.
 
 ## Troubleshooting integrations
diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md
index e823391401d..aee052aeaa1 100644
--- a/doc/user/project/integrations/webhooks.md
+++ b/doc/user/project/integrations/webhooks.md
@@ -48,7 +48,7 @@ specific to a group, including:
 - [Group member events](webhook_events.md#group-member-events)
 - [Subgroup events](webhook_events.md#subgroup-events)
 
-## Configure a webhook
+## Configure a webhook in GitLab
 
 You can configure a webhook for a group or a project.
 
@@ -60,6 +60,72 @@ You can configure a webhook for a group or a project.
 1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](overview.md#ssl-verification).
 1. Select **Add webhook**.
 
+## Configure your webhook receiver endpoint
+
+Webhook receivers should be *fast* and *stable*.
+Slow and unstable receivers may be disabled temporarily to ensure system reliability.
+If you are writing your own endpoint (web server) to receive GitLab webhooks, keep in mind the following:
+
+- Your endpoint should send its HTTP response as fast as possible.
+  You should aim for sub-second response times in all circumstances.
+  If the response takes longer than the configured timeout, GitLab assumes the
+  hook failed, which can lead to retries and potentially cause duplicate
+  events.
+  To customize the timeout, see
+  [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered).
+- Your endpoint should ALWAYS return a valid HTTP response. If not,
+  GitLab assumes the hook failed and retries it.
+  Most HTTP libraries take care of the response for you automatically but if
+  you are writing a low-level hook, this is important to remember.
+- GitLab usually ignores the HTTP status code returned by your endpoint,
+  unless the [`web_hooks_disable_failed` feature flag is set](#failing-webhooks).
+
+Best practices for a webhook receiver:
+
+- Prefer to return `200` or `201` status responses.
+  Only return error statuses (in the `4xx` range) to
+  indicate that the webhook has been misconfigured. For example, if your receiver
+  only supports push events, it is acceptable to return `400` if sent an issue
+  payload, since that is an indication that the hook has been set up
+  incorrectly. Alternatively, it is acceptable to ignore unrecognized event
+  payloads. Never return `500` status responses if the event has been handled.
+- Your service should be idempotent. In some circumstances (including
+  timeouts), the same event may be sent twice. Be prepared to handle duplicate
+  events. You can reduce the chances of this by ensuring that your endpoint is
+  reliably fast and stable.
+- Keep response payloads as short as possible. Empty responses are
+  fine. GitLab does not examine the response body, and it is only
+  stored so you can examine it later in the logs.
+- Limit the number and size of response headers. Only send headers that would
+  help you diagnose problems when examining the web hook logs.
+- To support fast response times, perform I/O or computationally intensive
+  operations asynchronously. You may indicate that the webhook is
+  asynchronous by returning `201`.
+
+### Failing webhooks
+
+> - Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default.
+> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 14.9.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it available,
+ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`.
+The feature is not ready for production use.
+
+If a webhook fails repeatedly, it may be disabled automatically.
+
+Webhooks that return response codes in the `5xx` range are understood to be failing
+intermittently, and are temporarily disabled. This lasts initially
+for 10 minutes. If the hook continues to fail, the back-off period is
+extended on each retry, up to a maximum disabled period of 24 hours.
+
+Webhooks that return failure codes in the `4xx` range are understood to be
+misconfigured, and these are disabled until you manually re-enable
+them. These webhooks are not automatically retried.
+
+See [troubleshooting](#troubleshoot-webhooks) for information on
+how to see if a webhook is disabled, and how to re-enable it.
+
 ## Test a webhook
 
 You can trigger a webhook manually, to ensure it's working properly. You can also send
@@ -131,47 +197,7 @@ that the request is legitimate.
 Push events can be filtered by branch using a branch name or wildcard pattern
 to limit which push events are sent to your webhook endpoint. By default,
 all push events are sent to your webhook endpoint. You can configure branch filtering
-in the [webhook settings](#configure-a-webhook) in your project.
-
-## HTTP responses for your endpoint
-
-If you are writing your own endpoint (web server) to receive
-GitLab webhooks, keep in mind the following:
-
-- Your endpoint should send its HTTP response as fast as possible. If the response
-  takes longer than the configured timeout, GitLab assumes the hook failed and retries it.
-  To customize the timeout, see
-  [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered).
-- Your endpoint should ALWAYS return a valid HTTP response. If not,
-  GitLab assumes the hook failed and retries it.
-  Most HTTP libraries take care of the response for you automatically but if
-  you are writing a low-level hook, this is important to remember.
-- GitLab usually ignores the HTTP status code returned by your endpoint,
-  unless the [`web_hooks_disable_failed` feature flag is set](#failing-webhooks).
-
-### Failing webhooks
-
-> - Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default.
-> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 14.9.
-
-FLAG:
-On self-managed GitLab, by default this feature is not available. To make it available,
-ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`.
-The feature is not ready for production use.
-
-If a webhook fails repeatedly, it may be disabled automatically.
-
-Webhooks that return response codes in the `5xx` range are understood to be failing
-intermittently, and are temporarily disabled. This lasts initially
-for 10 minutes. If the hook continues to fail, the back-off period is
-extended on each retry, up to a maximum disabled period of 24 hours.
-
-Webhooks that return failure codes in the `4xx` range are understood to be
-misconfigured, and these are disabled until you manually re-enable
-them. These webhooks are not automatically retried.
-
-See [troubleshooting](#troubleshoot-webhooks) for information on
-how to see if a webhook is disabled, and how to re-enable it.
+in the [webhook settings](#configure-a-webhook-in-gitlab) in your project.
 
 ## How image URLs are displayed in the webhook body