Add latest changes from gitlab-org/gitlab@master
This commit is contained in:
GitLab Bot
parent
cd49d91db3
commit
b6a77bc222
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
<!-- This redirect file can be deleted after <2022-06-17>. -->
|
||||
<!-- Redirects that point to other docs in the same project expire in three months. -->
|
||||
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
|
||||
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -819,7 +819,8 @@ Regardless of the tag names, the relative order of the reference tags determines
|
|||
numbering.
|
||||
|
||||
<!--
|
||||
Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test.
|
||||
The following codeblock uses HTML to skip the Vale ReferenceLinks test.
|
||||
Do not change it back to a markdown codeblock.
|
||||
-->
|
||||
|
||||
<pre class="highlight"><code>A footnote reference tag looks like this: [^1]
|
||||
|
|
@ -926,7 +927,8 @@ ___
|
|||
Examples:
|
||||
|
||||
<!--
|
||||
Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test.
|
||||
The following codeblock uses HTML to skip the Vale ReferenceLinks test.
|
||||
Do not change it back to a markdown codeblock.
|
||||
-->
|
||||
|
||||
<pre class="highlight"><code>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:
|
||||
|
||||
<!--
|
||||
Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test.
|
||||
The following codeblock uses HTML to skip the Vale ReferenceLinks test.
|
||||
Do not change it back to a markdown codeblock.
|
||||
-->
|
||||
|
||||
<pre class="highlight"><code>- 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.
|
|||
</code></pre>
|
||||
|
||||
- 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:
|
||||
|
|
|
|||
|
|
@ -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 <your email address>
|
||||
```
|
||||
|
||||
## 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?
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue